Commerce – 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://pos.crowdtwist.com/fulfillment
HTTP Header X-CT-Authorization = CTApiKey [ClientSecretKey]
Note: there is a space between CTAPIKey and the Secret Key value


Request

Field Name Sample Value Required Format Notes
URL PARAMETERSnone
QUERY STRING PARAMETERSnone
HTTP HEADER
ClientSecretKey QWERTYUIOP Yes String  


Request Body

Field Name Validation Required Format Notes
original_receipt_id Not null Yes String This is the client’s receipt id of the original purchase.
fuflillment_id Not null, unique 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 Not null, ISO-8601 compliant 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 Not null Yes Array This is the array of items to be fulfilled.
ITEMS ARRAY
sku Not null Yes String The SKU string identifier of the item that is being fulfilled.
quantity Not null; greater than zero Yes Interger The number of this item with this SKU is being fulfilled.
is_awaiting_fulfillment 1 or 0 No Boolean If the item is awaiting to be fulfilled.


Successful Response – Request Body

Field Name Sample Value Required Format Description
receipt_id 18 Yes Interger 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 Interger 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
{
  "sku": "SKU_3",
  "points_awarded": 47,
  "date_item_purchased": "2016-06-15T15:42:05"
}
{
  "sku": "SKU_3",
  "points_awarded": 47,
  "date_item_purchased": "2016-06-15T15:42:05"
}
No JSON Array List of items (with 1 quantity) and the points given for each of them through this fulfillment.
BREAKDOWN ARRAY
sku SKU_3 No Integer 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_purcahsed 2016-06-15T15:42:05 Yes Integer The date that this item was purchased. 


Error Response

Field Name Sample Value Required Format Description
system FulfillmentController Yes String A machine readable code that describes the error.
reason missing_data Yes String Type of error.
description FulfillmentController Yes Missing Data Exception 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


Sample Request – During Purchase
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_pending” 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,  // Add is_awaiting_fulfillment flag for items being fulfilled.
      "price": 21.22,
      "quantity": 2,
      "transaction_id": 2
    },
    {
      "sku": "sku_2",
      "price": 3.22,
      "quantity": 1,
      "transaction_id": 1
    }
  ]
}
{
  "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,  // Add is_awaiting_fulfillment flag for items being fulfilled.
      "price": 21.22,
      "quantity": 2,
      "transaction_id": 2
    },
    {
      "sku": "sku_2",
      "price": 3.22,
      "quantity": 1,
      "transaction_id": 1
    }
  ]
}

Sample Request – Partial Fulfillment
What if only a subset of items need to be fulfilled? 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",
      "is_awaiting_fulfillment": true,  // Add is_pending here.
      "price": 21.22,
      "quantity": 1,
      "transaction_id": 1
    },
    {
      "sku": "sku_1",
      "price": 21.22,
      "quantity": 1,
      "transaction_id": 1
    }
  ]
}
{
"items": [
    {
      "sku": "sku_1",
      "is_awaiting_fulfillment": true,  // Add is_pending here.
      "price": 21.22,
      "quantity": 1,
      "transaction_id": 1
    },
    {
      "sku": "sku_1",
      "price": 21.22,
      "quantity": 1,
      "transaction_id": 1
    }
  ]
}

Sample Request – During Fulfillment
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
    }
  ]
}
{
  "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 Successful Response: Status Code 200

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

Sample Error Response: Status Code 400

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

Sample Error Response: Status Code 400

{
  "system": "FulfillmentController",
  "reason": "missing_data",
  "description": "Missing Data Exception.",
  "message": "Date fulfilled is missing from the fulfillment request."
}
{
  "system": "FulfillmentController",
  "reason": "missing_data",
  "description": "Missing Data Exception.",
  "message": "Date fulfilled is missing from the fulfillment request."
}

Sample Error Response: Status Code 400

{
  "system": "FulfillmentController",
  "reason": "sku_not_found",
  "description": "Sku Not Avaiable For Fulfillment.",
  "message": "Sku [sku_2] being processed for fulfillment but isn't available for fulfillment."
}
{
  "system": "FulfillmentController",
  "reason": "sku_not_found",
  "description": "Sku Not Avaiable For Fulfillment.",
  "message": "Sku [sku_2] being processed for fulfillment but isn't available for fulfillment."
}