Fulfillment
Request Details
Item | Value |
Description | The fulfillment API is used at time of purchase fulfillment for items that were not fulfilled at the original time of purchase. |
Method | POST |
Endpoint | https://[environment]pos[client_id].crowdtwist.com/fulfillment |
HTTP Header | X-CT-Authorization = CTApiKey [API Key] Note: there is a space between CTApiKey and the API Key value |
Content Type | application/json |
Request
Field Name | Sample Value | Required | Format | Description |
URL PARAMETERS – none | ||||
QUERY PARAMETERS – none Note: This request does not support URL or query parameters. |
Request Body
Field Name | Sample Value | Required | Format | Description |
original_receipt_id | receipt123 | Yes | String | This is the client’s receipt id of the original purchase. |
fulfillment_id | fulfillment123 | Yes | String | For each fulfillment, this is the identifier to give this fulfillment request. This must be unique identifier to this request and it should map to the fulfillment request in the client’s system. |
date_fulfilled | 2016-06-15T15:42:05 | Yes | String | The date the item is being fulfilled. This date must be an ISO-8601 compliant date field with offset appended to it. |
items | See the ITEMS ARRAY section. | Yes | Array (Item Objects) | This is the array of items to be fulfilled. |
ITEMS ARRAY | ||||
sku | sku_1 | Yes | String | The SKU string identifier of the item that is being fulfilled. |
quantity | 2 | Yes | Integer | The quantity with this SKU is being fulfilled. |
Response
Response Body
Field Name | Sample Value | Required | Format | Description |
receipt_id | 18 | Yes | Integer | The purchase receipt that is found that matched the receipt sent in. This is the receipt identifier that is CrowdTwist’s identifier in CrowdTwist’s system. |
total_points_awarded | 235 | Yes | Integer | The number of points awarded due to this fulfillment transaction. |
bonus_points_awarded | 190 | Yes | Integer | The number of the points above that are bonus points. |
user_id | 42529648 | Yes | Integer | The user found in our system that matches the user found on the purchase receipt. This user id is the identifier of the user in CrowdTwist’s system. |
breakdown | See the BREAKDOWN ARRAY section. | Yes | Array | List of items (with 1 quantity) and the points given for each of them through this fulfillment. |
BREAKDOWN ARRAY | ||||
sku | SKU_1 | Yes | String | The sku of the item that was fulfilled. |
points_awarded | 47 | Yes | Integer | The number of points awarded for this one item that was fulfilled. |
date_item_purchased | 2016-06-15T15:42:05 | Yes | String | The date that this item was purchased. |
Error Responses
Field Name | Sample Value | Required | Format | Description |
system | pos | Yes | String | A machine readable code that describes the error. |
reason | missing_data | Yes | String | Type of error. |
description | FulfillmentController | Yes | String | A short, descriptive sentence detailing the error. |
message | Fulfillment must include original receipt id to process a fulfillment | Yes | String | A longer, descriptive sentence detailing the error. |
Error Response Codes
Error | Error Code | Description | Reason |
Input Error | 4xx | Returned whenever the request is missing required fields, including situations in which the body is malformed (e.g. HTTP method not supported, receipt not found, etc.). | – missing_data – not_unique – receipt_not_found – quantity_too_large – sku_not_found – not_supported (if an endpoint is not supported, a status HTTP code of 405 will be returned) – invalid |
Server Error | 5xx | HTTP error status code is returned due to an error that occurred in the backend. | – internal_error: unexpected error occurred in the CrowdTwist backend – not_configured: error occurs when an configuration has not been configured yet |
Example Response Codes
Response Code | System | Reason | Description | Message |
400 | pos | missing_data | Required field is missing. | Fulfillment must include original receipt id to process a fulfillment. |
400 | pos | missing_data | Required field is missing. | Date fulfilled is missing from the fulfillment request. |
400 | pos | missing_data | Required field is missing. | Fulfillment id is missing. |
400 | pos | missing_data | Required field is missing. | Fulfillment must include fulfillment items. |
400 | pos | sku_not_found | Receipt contains invalid data. | Sku [sku_2] being processed for fulfillment but isn't available for fulfillment. |
Samples
Sample Request Body - During purchase
Note: When the purchase is made, all items (including items being fulfilled) should be appended to the purchase. In order to distinguish which items need to be fulfilled, a “is_awaiting_fulfillment” flag must be set to true.
Sample Request Body - Partial Fulfillment
Note: If only 1 item out of a set of 4 items need to be fulfilled, items should be put into separate line items.
Sample Request Body - During Fulfillment
Note: When an item is to be fulfilled, send in the original receipt id and the SKU(s) that need to be fulfilled. In this example, two items of sku_1 and 1 item of sku_2 are being fulfilled.
Sample Response Body
Sample Error Response