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.

{ "receipt_id": "receipt123", "order_id": "order123", "user_id": "user123", "total": 119.64, "subtotal": 110.78, "date_purchased": "2012-04-23T18:25:43.511+00:00", "channel_id": 1, "currency": "USD", "custom_data": { "store_id": "store1", "register_id": "register1", "cashier_id": "cashier1", "employee_id": "employee_123" }, "items": [ { "sku": "sku_1", "is_awaiting_fulfillment": true, "price": 21.22, "quantity": 2, "transaction_id": 2 }, { "sku": "sku_2", "price": 3.22, "quantity": 1, "transaction_id": 1 } ] }

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.

{ "items": [ { "sku": "sku_1", "price": 21.22, "quantity": 1, "transaction_id": 1 }, { "sku": "sku_2", "price": 3.22, "quantity": 1, "transaction_id": 1 } ] }

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.

{ "fulfillment_id": "fulfillment123", "original_receipt_id": "receipt123", "date_fulfilled": "2012-04-23T18:25:43.511+00:00", "items": [ { "sku": "sku_1", "quantity": 2 }, { "sku": "sku_2", "quantity": 1 } ] }

 

Sample Response Body

{ "receipt_id": 18, "total_points_awarded": 235, "bonus_points_awarded": 190, "user_id": 42529648, "breakdown": [ { "sku": "SKU_1", "points_awarded": 47, "date_item_purchased": "2016-06-15T15:42:05" } ] }

 

Sample Error Response

{ "system": "pos", "reason": "missing_data", "description": "Missing Data Exception.", "message": "Fulfillment must include original receipt id to process a fulfillment." }