Sending items
items on Open a session says what the customer is buying. ShotPay
stores each line with the session, carries it onto the contract the session
becomes, and shows it to the customer in their account and to you on the order.
It comes back as Order Items on the session and the
contract.
Items are optional, and nothing ties them to total_amount. Tax, shipping and
discounts sit outside the lines, so the lines need not add up to the total.
Every item carries five fields: name, SKU, price, image and quantity. Name, price and quantity are required. SKU and image are stored as null when a product has none.
How many lines an order may carry depends on the shape it is sent in, and each
section below says so. More than that is a 422 on items. A line missing a
required field, or carrying one of the wrong type, is a 422 naming the field —
items.0.quantity, for example — and no session is opened either way.
Describing the lines yourself
Leave out items_source, or send shotpay, and write each line in ShotPay's
own shape. An order in this shape carries at most 50 lines.
| Field | Type | Required | Notes |
|---|---|---|---|
name |
string | Yes | Max 255 characters. |
sku |
string or null | No | Max 255 characters. |
quantity |
integer | Yes | 1 to 999,999. |
unit_amount |
integer | Yes | The price of one unit in cents — 49999 for $499.99. |
image_url |
string or null | No | HTTPS only; a plain http:// URL is refused. Max 2048 characters. |
{
"items": [
{ "name": "Hunting Rifle", "sku": "RF-100", "quantity": 1, "unit_amount": 49999, "image_url": "https://cdn.store.example/rifle.jpg" },
{ "name": "Scope", "quantity": 2, "unit_amount": 12999 }
]
}
Forwarding BigCommerce's own cart lines
Send items_source: "bigcommerce" to pass BigCommerce cart lines exactly as
BigCommerce returns them: one entry of line_items.physical_items or
line_items.digital_items from the Carts API's GET /v3/carts/{cartId}.
ShotPay reads the fields below from each line and ignores the rest. An order
carries at most 50 lines, the same cart limit the
BigCommerce app holds a store's carts to; the app
records items this way itself, and this is for an integration of your own.
| Item field | Read from |
|---|---|
| name | name — cut to 255 characters if longer |
| SKU | sku — cut to 255 characters if longer |
| price | sale_price — dollars, after every discount, converted to cents; at most 21,474,836.47 |
| image | image_url — dropped rather than refused when it is not an HTTPS URL |
| quantity | quantity — 1 to 999,999 |
{
"items_source": "bigcommerce",
"items": [
{
"id": "6e193ce6-f327-4dcc-b75e-72cf6738525e",
"product_id": 12,
"variant_id": 358,
"name": "T-Shirt",
"sku": "SMGREEN",
"quantity": 2,
"list_price": 12.5,
"sale_price": 11.1,
"image_url": "https://cdn11.bigcommerce.com/s-abc/products/12/images/1/tshirt.png"
}
]
}