IntroductionLast updated: 12/02/2021

The OTB Fulfillment API is a RESTful API, that uses a HTTP protocol for communication. HTTP GET, POST, PUT, PATCH and DELETE methods are used to access the API.

How to start

To begin using OTB Fulfillment API, follow these steps:

Click Avatar on navigation bar API Key
Choose ENABLE API ACCESS if you haven't enable API access before
Click button to copy your unique API Key

API Key

The API Key is a secret key and unique to each user, which is used to access the API. You can enable the API and generate an API Key for your account by following these steps above How to start

You might want to copy your key and keep it secure. Do not expose it anywhere

Authentication

OTB Fulfillment uses HTTP authentication for the API requests.

To perform authorization, you need to add the Authorization header with API key to request:

Authorization: Bearer 4f9755ef34c64386a7dab938f2xxxxxx

Request endpoint

All API requests have to be sent to this URL:

https://otbzone.com/bot/api/ver-1

If you are using a proxy, make sure that all requests have host header set to otbzone.com/bot/api/ver-1

Request parameters

Some mandatory parameters (like object identifiers) must be included in the request URL path:

GET /orders/60338dfc95318394612164e7

Additional parameters can be passed as GET variables:

GET /orders?page=1&pageSize=20

Status Response Codes

We use standard HTTP codes to denote successful execution or indicate when errors occur. For some errors, the response will include additional information about the error, including an application error code and human readable error description.

Successful execution

Operations that execute successfully will return 2xx codes, and, where appropriate, will return the information requested directly in the response body. The table below shows the typical response codes:

Method	HTTP code	HTTP Description	Notes
GET	200	OK	For successful `GET` and `PUT` requests.
POST	201	Created	For a successful `POST` request will result in a new entity, e.g. placing an order
POST	204	No Content	For a successful request that produced no response (such as `DELETE` requests).

Error Handling

Operations that result in an error due to a problem on the client's part (eg invalid input) will be standard 4xx codes. Operations that result in an error due to a problem in the Rev server will return 5xx codes.

Where a standard HTTP error is sufficiently descriptive, e.g. 401 (Not Authorized) or 404 (Not Found), the response body will be empty. For other cases, we will use the generic response code for client error (400), and the response will include an error entity that gives further details about the error, including an application error code and a human readable error description.

HTTP code	HTTP Description	Notes
400	Bad Request	Issued when a malformed request was sent.
401	Unauthorized	This response is sent when your client failed to provide credentials or its credentials were invalid.
403	Forbidden	Returned when permissions do not allow the operation.
404	Not Found	When a particular resource doesn’t exist or couldn’t be found.
422	Missing or Invalid Data	The request cannot be processed either because it omitted required fields or because it contained invalid data. See the response for more details.
429	Too Many Requests	When an OAuth client exceeds the rate limit for API requests to a store.
500	Internal Server Error	When an error has occurred within the API.
503	Service Unavailable	When the store is “Down for Maintenance,” being upgraded to a new version, or is suspended due to administrative action.

Response body

The response body is always a JSON object that contain a response status boolean and the result of the action. If the status is true, then the action will be successful.

{
  "status": true, // Response status
  "message": "Succeed",
  "data": {
    // API method response data
  }
}

Sometimes the response includes paging information to allow browsing larger result set by adding page and pageSize GET parameters to the URL request.

{
  "status": true, // Response status
  "message": "Succeed",
  "data": {
    "data": [
      {
        // API method response data
      }
    ],
    "total": 6 // Total number of records
  }
}

Error response

If the API call is not successful, then the response status will be return false and the message attribute contains an error description.

{
  "status": false, // Response status
  "message": "No token provided!",
  "data": {
    // API method response error data
  }
}

Timestamps

All timestamps from the API are returned as integers in UNIX timestamp format

Rate limits

OTB Fulfillment API has a general rate limit of 120 API calls per minute. Additionally, endpoints that perform resource intensive operations (such as mockup generator) have a lower allowed request limit.

Product Type APIs

OTB Fulfillment has a list of Product Types. Product Types are a way to group similar products together, including product variants such as size, color, etc.

You can use API to get a list of all Product Types.

Get All Product Types

GET /product-types

Returns a list of Product Types available from OTB Fulfillment

Input parameters


                      None

Response data format

{
  "data": { // Response data
    "data": [ // Response data array
      {
        "name": string, // Product type name
        "sku": string, // Product type SKU
        "image": string, // Product type image url
        "attributes": [ // Product Type attribute array
          {
            "price": number, // Attribute option price
            "options": [ // Array of option attributes
              {
                "name": string, // Attribute option name
                "value": string // Attribute option value
              }
            ]
          },
          {
            "price": number, // Attribute option price
            "options": [ // Array of option attributes
              {
                "name": string, // Attribute option name
                "value": string // Attribute option value
              }
            ]
          }
        ],
        "uploadItems": [ // Product Type array upload items
          {
            "name": string, // Upload item name
            "width": number, // Upload item width
            "height": number, // Upload item height
            "isRequired": boolean // Upload item is required
          },
          {
            "name": string, // Upload item name
            "width": number, // Upload item width
            "height": number, // Upload item height
            "isRequired": boolean // Upload item is required
          }
        ]
      }
    ],
    "total": number // Total number of records
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Product APIs

The Products API resource lets you create, modify and delete products in a OTB Fulfillment store based on the Manual orders / API platform (you can create such store by going to the Stores section at your OTB Fulfillment dashboard.)

Each product will contain different variants (including Name, SKU, Product Type, Print Design, Price, etc)

Get All Products

GET /products or

GET /products?page=1&pageSize=20

Note: page default is 1 and pageSize default is 20

Returns the user's list of available Products from OTB Fulfillment.

Query string parameters


                      None

or

"page": number,
"pageSize": number

Field	Data Type	Description
page	number	Result set offset
pageSize	number	Number of items per page (max 100)

Response data format

{
  "data": { // Response data
    "data": [ // Response data array
      {
        "id": string, // Product ID
        "attributes": [ // Array of product attributes
          {
            "options": [ // Array of option attributes
              {
                "name": string, // Attribute option name
                "value": string // Attribute option value
              }
            ],
            "price": number // Attribute option price
          },
          {
            "options": [ // Array of option attributes
              {
                "name": string, // Attribute option name
                "value": string // Attribute option value
              }
            ],
            "price": number // Attribute option price
          }
        ],
        "createdAt": number, // Product created at timestamp
        "description": string, // Product type description
        "designDescription": string, // Product design description
        "imageUrl": string, // Product image url
        "name": string, // Product name
        "productTypeName": string, // Product type name
        "sku": string, // Product SKU
        "status": string, // Product status
        "updatable": boolean // Product updatable
      }
    ],
    "total": number, // Total number of records
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Get Product By Id

GET /products/{id}

Returns information about a single Product

Query string parameters

Field	Data Type	Description
id *	string	The ID of product

Response data format

{
  "data": { // Response data
    "id": string, // Product ID
    "attributes": [ // Array of attributes
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      },
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      }
    ],
    "createdAt": number, // Product created at timestamp
    "description": string, // Product type description
    "designDescription": string, // Product design description
    "imageUrl": string, // Product image url
    "name": string, // Product name
    "productTypeName": string, // Product type name
    "sku": string, // Product SKU
    "status": string, // Product status
    "updatable": boolean // Product updatable
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Create New Product

POST /products

Add a new product to the OTB Fulfillment

Request body

{
  "name": string,
  "sku": string,
  "status": string,
  "productTypeSku": string,
  "designDescription": string,
  "imageUrl": string,
  "printDesigns": [
    {
      "uploadTypeItemName": string,
      "imageUrl": string
    },
    {
      "uploadTypeItemName": string,
      "imageUrl": string
    }
  ]
}

Note: If the field * is required to have a value

Field Data Type Description

name * string Product Name

sku * string Product SKU

status string Product status with ACTIVATED(default) or INACTIVATED

productTypeSku * string Product type SKU (Reference: Product Type)

designDescription string For Glitter products, add design description if needed

imageUrl string Featured image url

printDesigns * array Array of print designs

uploadTypeItemName *	string	Upload type item name (Reference: Product Type)
imageUrl *	string	Print design image url

Response data format

{
  "data": { // Response data
    "id": string, // Product ID
    "attributes": [ // Array of attributes
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      },
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      }
    ],
    "createdAt": number, // Product created at timestamp
    "description": string, // Product type description
    "designDescription": string, // Product design description
    "imageUrl": string, // Product image url
    "name": string, // Product name
    "productTypeName": string, // Product type name
    "sku": string, // Product SKU
    "status": string, // Product status
    "updatable": boolean // Product updatable
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Update Product By Id

PUT /products/{id}

Modify existing Products

Query string parameters

Field	Data Type	Description
id *	string	The ID of product

Request body

{
  "name": string,
  "sku": string,
  "status": string,
  "designDescription": string,
  "imageUrl": string,
  "printDesigns": [
    {
      "uploadTypeItemName": string,
      "imageUrl": string
    }
  ]
}

Note: Please note that in the required text, you only need to specify the fields to change.

Field Data Type Description

name string Product Name

sku string Product SKU

status string Product status with ACTIVATED(default) or INACTIVATED

designDescription string For Glitter products, add design description if needed

imageUrl string Featured image url

printDesigns array Array of print designs

uploadTypeItemName	string	Upload type item name (Reference: Product Type)
imageUrl	string	Print design image url

Update a product's name

{
  "name": "Premium TShirt - Two Side",
  "printDesigns": [
    {
      "uploadTypeItemName": "Front Design"
    }
  ]
}

Update a product's SKU

{
  "sku": "PREMIUM_TSHIRT-TWO_SIDE",
  "printDesigns": [
    {
      "uploadTypeItemName": "Front Design"
    }
  ]
}

Update a product's add print design

{
  "printDesigns": [
    {
      "uploadTypeItemName": "Front Design"
    },
    {
      "uploadTypeItemName": "Back Design",
      "imageUrl": "https://storage.googleapis.com/otbzone/assets/4500x5400.jpg"
    }
  ]
}

Update a product's print design

{
  "printDesigns": [
    {
      "uploadTypeItemName": "Front Design",
      "imageUrl": "https://storage.googleapis.com/otbzone/assets/4500x5400.jpg"
    },
    {
      "uploadTypeItemName": "Back Design"
    }
  ]
}

Update a product's remove all print designs

{
  "name": "Premium TShirt - Two Side",
  "sku": "PREMIUM_TSHIRT-TWO_SIDE"
}

or

{

}

Response data format

{
  "data": { // Response data
    "id": string, // Product ID
    "attributes": [ // Array of attributes
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      },
      {
        "options": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "price": number // Attribute option price
      }
    ],
    "createdAt": number, // Product created at timestamp
    "description": string, // Product type description
    "designDescription": string, // Product design description
    "imageUrl": string, // Product image url
    "name": string, // Product name
    "productTypeName": string, // Product type name
    "sku": string, // Product SKU
    "status": string, // Product status
    "updatable": boolean // Product updatable
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Order APIs

The Orders API is the most important part of the OTB API.

It allows you to create new orders, update orders and confirm them for fulfillment.

Get All Orders

GET /orders or GET /orders?page=1&pageSize=20

Note: page default is 1 and pageSize default is 20

Returns the list of Orders available in the OTB Fulfillment

Query string parameters


                      None

or

"page": number,
"pageSize": number

Field	Data Type	Description
page	number	Result set offset
pageSize	number	Number of items per page (max 100)

Response data format

{
  "data": { // Response data
    "data": [ // Response data array
      {
        "id": string, // Order ID
        "address": { // The order's address information
          "id": string, // Address ID
          "firstName": string, // Address first name
          "lastName": string, // Address last name
          "state": { // Address state information
            "id": number, // State ID
            "name": string, // State name
            "stateCode": string // State code
          },
          "country": { // Address country information
            "id": string, // Country ID
            "name": string // Country name
          },
          "city": string, // Order city
          "email": string, // Order email
          "otherState": string, // Order other state
          "phone": string, // Order phone
          "street": string, // Order street
          "street2": string, // Order street2
          "zipcode": string // Order zipcode
        },
        "addedTrackingCode": number, // The total tracking code entered of the order item
        "addressFullName": string, // Order address full name
        "country": string, // Order country
        "coupon": { // Coupon code information after being applied
          "couponAmount": number, // Coupon amount
          "couponCode": string, // Coupon code
          "couponMaxAmount": number, // Coupon max amount
          "description": string, // Description of coupon code
          "fromDate": number, // Coupon code from date
          "hasCouponAdded": boolean, // Has coupon added
          "isCouponCodeValid": boolean, // Coupon code valid
          "isCouponFixedValue": boolean, // Coupon fixed value
          "message": string, // Coupon code message
          "name": string, // Coupon code name
          "toDate": number, // Coupon code to date
          "totalDiscountAmount": number, // Total discount amount
          "totalDiscountShippingAmount": number // Total discount shipping amount
        },
        "couponCode": string, // Order coupon code
        "isAllowAddressUpdatable": boolean, // If your order address is wrong, admin can confirm the value, you can update the address
        "isDraft": boolean, // If order is draft, the value is true, otherwise if placed order, the value is false
        "isValidAddress": boolean, // If the order has verified the address value is true, otherwise if the order has not verified, the value is false
        "orderItems": [ // Array of order items of the order
          {
            "id": string, // Order item ID
            "applyFastShipping": boolean, // Order item apply fast shipping
            "attributes": string[], // Array of attributes for the order item
            "createdAt": number, // Order item created at timestamp
            "designDescription": string, // Product design description
            "price": number, // Order item price
            "productId": string, // Product ID
            "productName": string, // Product name
            "productSku": string, // Product SKU
            "productTypeName": string, // Product type name
            "qty": number, // Order item quantity
            "imageUrl": string, // Product image url
            "shippingPrice": number, // Order item shipping price
            "sellerStatus": string // Order item status
          },
          {
            "id": string, // Order item ID
            "applyFastShipping": boolean, // Order item apply fast shipping
            "attributes": string[], // Array of attributes for the order item
            "createdAt": number, // Order item created at timestamp
            "price": number, // Order item price
            "productId": string, // Product ID
            "productName": string, // Product name
            "productSku": string, // Product SKU
            "productTypeName": string, // Product type name
            "qty": number, // Order item quantity
            "imageUrl": string, // Product image url
            "shippingPrice": number, // Order item shipping price
            "sellerStatus": string // Order item status
          }
        ],
        "orderStatus": string, // All status of the order item
        "refId": string, // Order reference ID
        "selfId": string, // Order self ID
        "subTotalAmount": number, // Order sub total amount
        "totalAmount": number, // Order total amount
        "totalDiscountAmount": number, // Order total discount amount
        "totalDiscountShippingAmount": number, // Order total discount shipping amount
        "totalOrderItems": number, // Order total order items
        "totalQty": number, // Order total quantity
        "totalShippingAmount": number, // Order total shipping amount
        "trackingCodes": string[], // This is an array of string tracking code of the order item
        "createdAt": number, // Order created at timestamp
        "placedAt": number // Order placed at timestamp
      }
    ],
    "total": number // Total number of records
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Get Order By Id

GET /orders/{id}

Returns information about a single Order

Query string parameters

Field	Data Type	Description
id *	string	The ID of order

Response data format

{
  "data": { // Response data
    "id": string, // Order ID
    "address": { // The order's address information
      "id": string, // Address ID
      "firstName": string, // Address first name
      "lastName": string, // Address last name
      "state": { // Address state information
        "id": number, // State ID
        "name": string, // State name
        "stateCode": string // State code
      },
      "country": { // Address country information
        "id": string, // Country ID
        "name": string // Country name
      },
      "city": string, // Order city
      "email": string, // Order email
      "otherState": string, // Order other state
      "phone": string, // Order phone
      "street": string, // Order street
      "street2": string, // Order street2
      "zipcode": string // Order zipcode
    },
    "addedTrackingCode": number, // The total tracking code entered of the order item
    "addressFullName": string, // Order address full name
    "country": string, // Order country
    "coupon": { // Coupon code information after being applied
      "couponAmount": number, // Coupon amount
      "couponCode": string, // Coupon code
      "couponMaxAmount": number, // Coupon max amount
      "description": string, // Description of coupon code
      "fromDate": number, // Coupon code from date
      "hasCouponAdded": boolean, // Has coupon added
      "isCouponCodeValid": boolean, // Coupon code valid
      "isCouponFixedValue": boolean, // Coupon fixed value
      "message": string, // Coupon code message
      "name": string, // Coupon code name
      "toDate": number, // Coupon code to date
      "totalDiscountAmount": number, // Total discount amount
      "totalDiscountShippingAmount": number // Total discount shipping amount
    },
    "couponCode": string, // Order coupon code
    "isAllowAddressUpdatable": boolean, // If your order address is wrong, admin can confirm the value, you can update the address
    "isDraft": boolean, // If order is draft, the value is true, otherwise if placed order, the value is false
    "isValidAddress": boolean, // If the order has verified the address value is true, otherwise if the order has not verified, the value is false
    "orderItems": [ // Array of order items of the order
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "designDescription": string, // Product design description
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      },
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      }
    ],
    "orderStatus": string, // All status of the order item
    "refId": string, // Order reference ID
    "selfId": string, // Order self ID
    "subTotalAmount": number, // Order sub total amount
    "totalAmount": number, // Order total amount
    "totalDiscountAmount": number, // Order total discount amount
    "totalDiscountShippingAmount": number, // Order total discount shipping amount
    "totalOrderItems": number, // Order total order items
    "totalQty": number, // Order total quantity
    "totalShippingAmount": number, // Order total shipping amount
    "trackingCodes": string[], // This is an array of string tracking code of the order item
    "createdAt": number, // Order created at timestamp
    "placedAt": number // Order placed at timestamp
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Create New Order

POST /orders

Add a new order into OTB Fulfillment

Request body

{
  "order": {
    "isDraft": boolean,
    "refId": string,
    "couponCode": string,
    "orderItems": [
      {
        "qty": number,
        "productSku": string,
        "attributes": [
          {
            "name": string,
            "value": string
          }
        ],
        "designDescription": string,
        "applyFastShipping": boolean
      }
    ]
  },
  "address": {
    "firstName": string,
    "lastName": string,
    "phone": string,
    "email": string,
    "street": string,
    "street2": string,
    "country": string,
    "state": string,
    "otherState": string,
    "city": string,
    "zipcode": string
  }
}

Note: If the field * is required to have a value

Field

Data Type

Description

order *

object

Order information

isDraft

boolean

If order is draft, the value is true, otherwise if order is placed, the value is false

refId

string

Order reference ID

couponCode

string

Order coupon code

orderItems *

array

Array of order items

qty *

number

Order item quantity

productSku *

string

Product SKU

attributes *

array

Array of attributes

name *	string	Attribute option name
value *	string	Attribute option value

designDescription

string

For Glitter products, add design description if needed (Note: If the design description already exists in the product, it will overwrite it and get the new value)

applyFastShipping

boolean

Order item apply fast shipping

address *

object

Address information

firstName *	string	Address first name
lastName *	string	Address last name
phone	string	Address phone
email	string	Address email
street *	string	Address street
street2	string	Address street2
country *	string	Address country
state	string	If state is US then the field is require
otherState	string	Address other state
city *	string	Address city
zipcode *	string	Address zipcode

Response data format

{
  "data": { // Response data
    "id": string, // Order ID
    "address": { // The order's address information
      "id": string, // Address ID
      "firstName": string, // Address first name
      "lastName": string, // Address last name
      "state": { // Address state information
        "id": number, // State ID
        "name": string, // State name
        "stateCode": string // State code
      },
      "country": { // Address country information
        "id": string, // Country ID
        "name": string // Country name
      },
      "city": string, // Order city
      "email": string, // Order email
      "otherState": string, // Order other state
      "phone": string, // Order phone
      "street": string, // Order street
      "street2": string, // Order street2
      "zipcode": string // Order zipcode
    },
    "addedTrackingCode": number, // The total tracking code entered of the order item
    "addressFullName": string, // Order address full name
    "country": string, // Order country
    "coupon": { // Coupon code information after being applied
      "couponAmount": number, // Coupon amount
      "couponCode": string, // Coupon code
      "couponMaxAmount": number, // Coupon max amount
      "description": string, // Description of coupon code
      "fromDate": number, // Coupon code from date
      "hasCouponAdded": boolean, // Has coupon added
      "isCouponCodeValid": boolean, // Coupon code valid
      "isCouponFixedValue": boolean, // Coupon fixed value
      "message": string, // Coupon code message
      "name": string, // Coupon code name
      "toDate": number, // Coupon code to date
      "totalDiscountAmount": number, // Total discount amount
      "totalDiscountShippingAmount": number // Total discount shipping amount
    },
    "couponCode": string, // Order coupon code
    "isAllowAddressUpdatable": boolean, // If your order address is wrong, admin can confirm the value, you can update the address
    "isDraft": boolean, // If order is draft, the value is true, otherwise if placed order, the value is false
    "isValidAddress": boolean, // If the order has verified the address value is true, otherwise if the order has not verified, the value is false
    "orderItems": [ // Array of order items of the order
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "designDescription": string, // Product design description
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      },
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      }
    ],
    "orderStatus": string, // All status of the order item
    "refId": string, // Order reference ID
    "selfId": string, // Order self ID
    "subTotalAmount": number, // Order sub total amount
    "totalAmount": number, // Order total amount
    "totalDiscountAmount": number, // Order total discount amount
    "totalDiscountShippingAmount": number, // Order total discount shipping amount
    "totalOrderItems": number, // Order total order items
    "totalQty": number, // Order total quantity
    "totalShippingAmount": number, // Order total shipping amount
    "trackingCodes": string[], // This is an array of string tracking code of the order item
    "createdAt": number, // Order created at timestamp
    "placedAt": number // Order placed at timestamp
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Update Order By Id

PUT /orders/{id}

Only used for draft order. If order is not order draft, it will return error.

Query string parameters

Field	Data Type	Description
id *	string	The ID of order

Request body

{
  "order": {
    "isDraft": boolean,
    "refId": string,
    "couponCode": string,
    "orderItems": [
      {
        "id": string,
        "qty": number,
        "productSku": string,
        "attributes": [
          {
            "name": string,
            "value": string
          }
        ],
        "designDescription": string,
        "applyFastShipping": boolean
      }
    ]
  },
  "address": {
    "firstName": string,
    "lastName": string,
    "phone": string,
    "email": string,
    "street": string,
    "street2": string,
    "country": string,
    "state": string,
    "otherState": string,
    "city": string,
    "zipcode": string
  }
}

Note: Please note that in the required text, you only need to specify the fields to change.

Field

Data Type

Description

order

object

Order information

isDraft

boolean

If order is draft, the value is true, otherwise if order is placed, the value is false

refId

string

Order reference ID

couponCode

string

Order coupon code

orderItems

array

Array of order items

id

string

Order item ID

qty

number

Order item quantity

productSku

string

Product SKU

attributes

array

Array of attributes

name	string	Attribute option name
value	string	Attribute option value

designDescription

string

For Glitter products, add design description if needed (Note: If the design description already exists in the product, it will overwrite it and get the new value)

applyFastShipping

boolean

Order item apply fast shipping

address

object

Address information

firstName	string	Address first name
lastName	string	Address last name
phone	string	Address phone
email	string	Address email
street	string	Address street
street2	string	Address street2
country	string	Address country
state	string	If state is US then the field is require
otherState	string	Address other state
city	string	Address city
zipcode	string	Address zipcode

Add an order item to an order

{
  "order": {
    "orderItems": [
      {
        "id": "60651e55c508a14e5653c868"
      },
      {
        "id": "6037439a953183946121657d"
      },
      {
        "qty": 2,
        "productSku": "Hawaiian Shirt",
        "attributes": [
          {
            "name": "Apparel Size",
            "value": "XL"
          }
        ]
      }
    ]
  }
}

Update the attribute and apply fast shipping to the order item of an order

{
  "order": {
    "orderItems": [
      {
        "id": "60651e55c508a14e5653c868",
        "attributes": [
          {
            "name": "Mask Pack",
            "value": "Pack 3"
          }
        ],
        "applyFastShipping": true
      },
      {
        "id": "6037439a953183946121657d"
      },
      {
        "id": "606ac286bdf9ec47d5bc422c"
      }
    ]
  }
}

Keep the same order item

{
  "order": {
    "orderItems": [
      {
        "id": "60651e55c508a14e5653c868"
      },
      {
        "id": "6037439a953183946121657d"
      },
      {
        "id": "606ac286bdf9ec47d5bc422c"
      }
    ]
  }
}

Remove an order item

{
  "order": {
    "orderItems": [
      {
        "id": "60651e55c508a14e5653c868"
      },
      {
        "id": "606ac286bdf9ec47d5bc422c"
      }
    ]
  }
}

Response data format

{
  "data": { // Response data
    "id": string, // Order ID
    "address": { // The order's address information
      "id": string, // Address ID
      "firstName": string, // Address first name
      "lastName": string, // Address last name
      "state": { // Address state information
        "id": number, // State ID
        "name": string, // State name
        "stateCode": string // State code
      },
      "country": { // Address country information
        "id": string, // Country ID
        "name": string // Country name
      },
      "city": string, // Order city
      "email": string, // Order email
      "otherState": string, // Order other state
      "phone": string, // Order phone
      "street": string, // Order street
      "street2": string, // Order street2
      "zipcode": string // Order zipcode
    },
    "addedTrackingCode": number, // The total tracking code entered of the order item
    "addressFullName": string, // Order address full name
    "country": string, // Order country
    "coupon": { // Coupon code information after being applied
      "couponAmount": number, // Coupon amount
      "couponCode": string, // Coupon code
      "couponMaxAmount": number, // Coupon max amount
      "description": string, // Description of coupon code
      "fromDate": number, // Coupon code from date
      "hasCouponAdded": boolean, // Has coupon added
      "isCouponCodeValid": boolean, // Coupon code valid
      "isCouponFixedValue": boolean, // Coupon fixed value
      "message": string, // Coupon code message
      "name": string, // Coupon code name
      "toDate": number, // Coupon code to date
      "totalDiscountAmount": number, // Total discount amount
      "totalDiscountShippingAmount": number // Total discount shipping amount
    },
    "couponCode": string, // Order coupon code
    "isAllowAddressUpdatable": boolean, // If your order address is wrong, admin can confirm the value, you can update the address
    "isDraft": boolean, // If order is draft, the value is true, otherwise if placed order, the value is false
    "isValidAddress": boolean, // If the order has verified the address value is true, otherwise if the order has not verified, the value is false
    "orderItems": [ // Array of order items of the order
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "designDescription": string, // Product design description
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      },
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      }
    ],
    "orderStatus": string, // All status of the order item
    "refId": string, // Order reference ID
    "selfId": string, // Order self ID
    "subTotalAmount": number, // Order sub total amount
    "totalAmount": number, // Order total amount
    "totalDiscountAmount": number, // Order total discount amount
    "totalDiscountShippingAmount": number, // Order total discount shipping amount
    "totalOrderItems": number, // Order total order items
    "totalQty": number, // Order total quantity
    "totalShippingAmount": number, // Order total shipping amount
    "trackingCodes": string[], // This is an array of string tracking code of the order item
    "createdAt": number, // Order created at timestamp
    "placedAt": number // Order placed at timestamp
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Estimate order price

POST /estimate-order-price

Returns the estimated price when placing an order

Request body

{
  "order": {
    "couponCode": string,
    "orderItems": [
      {
        "qty": number,
        "productSku": string,
        "attributes": [
          {
            "name": string,
            "value": string
          }
        ],
        "applyFastShipping": boolean
      }
    ]
  },
  "address": {
    "firstName": string,
    "lastName": string,
    "phone": string,
    "email": string,
    "street": string,
    "street2": string,
    "country": string,
    "state": string,
    "otherState": string,
    "city": string,
    "zipcode": string
  }
}

Note: If the field * is required to have a value

Field

Data Type

Description

order *

object

Order information

couponCode

string

Order coupon code

orderItems *

array

Array of order items

qty *

number

Order item quantity

productSku *

string

Product SKU

attributes *

array

Array of attributes

name *	string	Attribute option name
value *	string	Attribute option value

applyFastShipping

boolean

Order item apply fast shipping

address *

object

Address information

firstName *	string	Address first name
lastName *	string	Address last name
phone	string	Address phone
email	string	Address email
street *	string	Address street
street2	string	Address street2
country *	string	Address country
state	string	If state is US then the field is require
otherState	string	Address other state
city *	string	Address city
zipcode *	string	Address zipcode

Response data format

{
  "data": { // Response data
    "items": [ // Array of order items
      {
        "qty": number, // Order item quantity
        "productSku": string, // Product SKU
        "attributes": [ // Array of option attributes
          {
            "name": string, // Attribute option name
            "value": string // Attribute option value
          }
        ],
        "applyFastShipping": boolean, // Order item apply fast shipping
        "status": number, // If the order item allows shipping the value is true, otherwise it is false
        "isAllowFastShipping": boolean, // Order item allow fast shipping
        "isCouponCodeValid": boolean, // Order item coupon code valid
        "discountAmount": number, // Order item discount amount
        "discountShippingAmount": number, // Order item discount shipping amount
        "price": number, // Order item price
        "productTypeId": number, // Order item product type ID
        "shippingPrice": number, // Order item shipping price
        "subPrice": number, // Order item sub price
        "totalPrice": number // Order item total price
      }
    ],

    "coupon": { // Coupon code information after being applied
      "id": string, // Coupon ID
      "badgeId": string, // Badge ID
      "couponAmount": number, // Coupon amount
      "couponCode": string, // Coupon code
      "couponMaxAmount": number, // Coupon max amount
      "description": string, // Description of coupon code
      "fromDate": number, // Coupon code from date
      "hasBadgeDefault": boolean,// Has badge default
      "hasCouponAdded": boolean, // Has coupon added
      "isCouponCodeValid": boolean, // Coupon code valid
      "isCouponFixedValue": boolean, // Coupon fixed value
      "message": string, // Coupon code message
      "name": string, // Coupon code name
      "toDate": number, // Coupon code to date
      "totalDiscountAmount": number, // Total discount amount
      "totalDiscountShippingAmount": number, // Total discount shipping amount
      "type": number // Type of coupon code
    },

    "subTotal": number, // Order sub total
    "shippingTotal": number, // Order shipping total
    "grandTotal": number // Order grand total
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Create An Instant Order

POST /instant-order

You can quickly upload your products and orders to the OTB dashboard without creating a product first.

This option is suitable for orders with products that are placed only once (for example, personalized orders)

Request body

{
  "order": {
    "isDraft": boolean,
    "refId": string,
    "couponCode": string,
    "orderItems": [
      {
        "product": {
          "name": string,
          "productTypeSku": string,
          "designDescription": string,
          "imageUrl": string,
          "printDesigns": [
            {
              "uploadTypeItemName": string,
              "imageUrl": string
            }
          ]
        },
        "attributes": [
          {
            "name": string,
            "value": string
          }
        ],
        "qty": number,
        "designDescription": string,
        "applyFastShipping": boolean
      }
    ]
  },
  "address": {
    "firstName": string,
    "lastName": string,
    "phone": string,
    "email": string,
    "street": string,
    "street2": string,
    "country": string,
    "state": string,
    "otherState": string,
    "city": string,
    "zipcode": string
  }
}

Note: If the field * is required to have a value

Field

Data Type

Description

order *

object

Order information

isDraft

boolean

If order is draft, the value is true, otherwise if order is placed, the value is false

refId

string

Order reference ID

couponCode

string

Order coupon code

orderItems *

array

Array of order items

product *

object

Product information

name *

string

Product Name

productTypeSku *

string

Product type SKU (Reference: Product Type)

designDescription

string

For Glitter products, add design description if needed

imageUrl

string

Featured image url

printDesigns *

array

Array of print designs

uploadTypeItemName *	string	Upload type item name (Reference: Product Type)
imageUrl *	string	Print design image url

attributes *

array

Array of attributes

name *	string	Attribute option name
value *	string	Attribute option value

qty *

number

Order item quantity

designDescription

string

For Glitter products, add design description if needed (Note: If the design description already exists in the product, it will overwrite it and get the new value)

applyFastShipping

boolean

Order item apply fast shipping

address *

object

Address information

firstName *	string	Address first name
lastName *	string	Address last name
phone	string	Address phone
email	string	Address email
street *	string	Address street
street2	string	Address street2
country *	string	Address country
state	string	If state is US then the field is require
otherState	string	Address other state
city *	string	Address city
zipcode *	string	Address zipcode

Response data format

{
  "data": { // Response data
    "id": string, // Order ID
    "address": { // The order's address information
      "id": string, // Address ID
      "firstName": string, // Address first name
      "lastName": string, // Address last name
      "state": { // Address state information
        "id": number, // State ID
        "name": string, // State name
        "stateCode": string // State code
      },
      "country": { // Address country information
        "id": string, // Country ID
        "name": string // Country name
      },
      "city": string, // Order city
      "email": string, // Order email
      "otherState": string, // Order other state
      "phone": string, // Order phone
      "street": string, // Order street
      "street2": string, // Order street2
      "zipcode": string // Order zipcode
    },
    "addedTrackingCode": number, // The total tracking code entered of the order item
    "addressFullName": string, // Order address full name
    "country": string, // Order country
    "coupon": { // Coupon code information after being applied
      "couponAmount": number, // Coupon amount
      "couponCode": string, // Coupon code
      "couponMaxAmount": number, // Coupon max amount
      "description": string, // Description of coupon code
      "fromDate": number, // Coupon code from date
      "hasCouponAdded": boolean, // Has coupon added
      "isCouponCodeValid": boolean, // Coupon code valid
      "isCouponFixedValue": boolean, // Coupon fixed value
      "message": string, // Coupon code message
      "name": string, // Coupon code name
      "toDate": number, // Coupon code to date
      "totalDiscountAmount": number, // Total discount amount
      "totalDiscountShippingAmount": number // Total discount shipping amount
    },
    "couponCode": string, // Order coupon code
    "isAllowAddressUpdatable": boolean, // If your order address is wrong, admin can confirm the value, you can update the address
    "isDraft": boolean, // If order is draft, the value is true, otherwise if placed order, the value is false
    "isValidAddress": boolean, // If the order has verified the address value is true, otherwise if the order has not verified, the value is false
    "orderItems": [ // Array of order items of the order
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "designDescription": string, // Product design description
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      },
      {
        "id": string, // Order item ID
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes for the order item
        "createdAt": number, // Order item created at timestamp
        "price": number, // Order item price
        "productId": string, // Product ID
        "productName": string, // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "imageUrl": string, // Product image url
        "shippingPrice": number, // Order item shipping price
        "sellerStatus": string // Order item status
      }
    ],
    "orderStatus": string, // All status of the order item
    "refId": string, // Order reference ID
    "selfId": string, // Order self ID
    "subTotalAmount": number, // Order sub total amount
    "totalAmount": number, // Order total amount
    "totalDiscountAmount": number, // Order total discount amount
    "totalDiscountShippingAmount": number, // Order total discount shipping amount
    "totalOrderItems": number, // Order total order items
    "totalQty": number, // Order total quantity
    "totalShippingAmount": number, // Order total shipping amount
    "trackingCodes": string[], // This is an array of string tracking code of the order item
    "createdAt": number, // Order created at timestamp
    "placedAt": number // Order placed at timestamp
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Order Item APIs

The Order Item API allows viewing of the order items that a user has placed.

Each order item belongs to one order.

Get All Order Items

GET /order-items or GET /order-items?page=1&pageSize=20

Note: page default is 1 and pageSize default is 20

Returns the list of order items from the OTB Fulfillment

Query string parameters


                      None

or

"page": number,
"pageSize": number

Field	Data Type	Description
page	number	Result set offset
pageSize	number	Number of items per page (max 100)

Response data format

{
  "data": { // Response data
    "data": [ // Response data array
      {
        "id": string, // Order item ID
        "addressFullName": string, // Order item address full name
        "applyFastShipping": boolean, // Order item apply fast shipping
        "attributes": string[], // Array of attributes
        "country": string, // Order item country
        "couponCode": string, // Order item coupon code
        "designDescription": string, // Product design description
        "discountAmount": number, // Order item discount amount
        "discountShippingAmount": number, // Order item discount shipping amount
        "imageUrl": string, // Order item imageUrl
        "isValidAddress": boolean, // Order item valid address
        "orderId": string, // Order ID
        "orderSelfId": string, // Order self ID
        "price": number, // Order item price
        "productName": string // Product name
        "productSku": string, // Product SKU
        "productTypeName": string, // Product type name
        "qty": number, // Order item quantity
        "shippingPrice": number, // Order item shipping price
        "status": string // Order item status
        "totalPrice": number, // Order item total price
        "createdAt": number, // Order created at timestamp
        "placedAt": number, // Order placed at timestamp
        "updatedAt": number // Order updated at timestamp
      }
    ],
    "total": number // Total number of records
  },
  "status": boolean, // Response status
  "message": string // Response message
}

Transaction APIs

Transaction API allows users to deposit, withdraw, view current balance and other functions that related to transactions.

You can use this API to get functions that relate to Transaction.

Get Current Balance

GET /balance

Returns the user's current balance from OTB Fulfillment

Query string parameters


                      None

Response data format

{
  "data": { // Response data
    "currentBalance": number // Current balance
  },
  "status": boolean, // Response status
  "message": string // Response message
}