Skip to content

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"
    }
  ]
}