Skip to content

Orders

Read a store's orders, and calculate the tax on and charge post-purchase add-ons against an order that has already been paid.

Updated View as Markdown

An order is the record of a completed checkout: who bought, what they bought, what was charged, and how it shipped. Two of the endpoints here read orders, and one calculates the tax on an add-on without charging it. The upsell endpoint is the one place in the API where an order is mutated and a card is charged.

Reach for orders when you are reconciling revenue, driving an order-status page, or syncing into an ERP. If all you need is tracking data, the fulfillments endpoints are cheaper and more direct.

Identifiers

Orders are addressed by order_id: a per-store sequential number that matches what the dashboard shows. It is not a database primary key, and it is only unique within your team. The same convention holds for customer_id, product_id and variant_id.

Three fields use UUIDs instead: fulfillment_id, transaction_id and reference_transaction_id. Treat them as opaque strings — they are stable, globally unique, and deliberately not sequential. No field on an order is a database primary key.

Money

Orders emit money as floating-point dollars — "total": 644.46 means $644.46. This covers subtotal, tax, shipping, shipping_insurance, hazmat_fee, surcharge, discount, total, every items[].price and items[].subtotal, and every transactions[].amount. hazmat_fee is the store’s hazmat fee on an order with powder or primers, 0 otherwise.

The upsell endpoint is the exception, and it is inconsistent in both directions: its request body takes items[].price and tax in integer cents, and the transaction.amount it returns is also in integer cents, while the order object in that same response is still in dollars. Parse the two halves separately. The upsell tax endpoint takes and returns integer cents only.

Values are JSON numbers, so a whole-dollar amount serializes without a fractional part ("discount": 25, not 25.00). Do not rely on the decimal places to detect the unit.

Order status

The status on every order is not the stored column. It is re-derived from the order’s transaction ledger on each read, because reversals are recorded as separate rows rather than by mutating the original payment. The derived value is one of:

pending, awaiting_payment, failed, completed, refunded, partially_refunded, void, partially_void, chargeback, partially_chargeback

Externally settled marketplace orders — currently GunBroker imports — carry no local payment ledger, so they report their stored status instead. That is the only way values like paid or shipped appear.

This matters when filtering: ?status= is matched against the stored column, so a filtered list can contain orders whose returned status is something else. Filter to narrow the result set, then branch on the value you actually get back.

What is included

List results embed items, transactions, the saved card summary and both addresses. They do not include fulfillments — that key is omitted entirely rather than returned empty. Only the single-order endpoint loads fulfillments and their shipments.

Addresses carry street, city, state and ZIP only. There is no recipient name, company, country or phone behind the address object, so a label cannot be reconstructed from an order response alone.

Line item properties

Each item’s properties is what the storefront attached to that cart line, or null. A theme’s product form sends them as properties[Name] fields, so a product builder’s choices arrive as, for example, {"Gun": "Glock 19 Gen 5", "Draw hand": "Right"}.

A name starting with an underscore is private: the customer never saw it. Some belong to the store’s theme, and FirearmCart’s own bookkeeping uses the same prefix, such as {"_upsell": true} on a line added through the upsell endpoint. Skip any underscore name you don’t recognize.

Errors

Orders use the platform-wide error envelope of error plus message, with one inconsistency worth coding around: a missing order is not_found on GET /v1/orders/{order_id} but order_not_found on the upsell and upsell tax endpoints. Match on the HTTP status, not the string.

Malformed upsell bodies return the stock validation shape (message plus a keyed errors object) rather than the error/message envelope, and rate limiting returns a bare {"message": "Too Many Attempts."}. See Errors for the full picture and Authentication for how abilities are granted.

List orders

GET/v1/orders
Returns a paginated list of the authenticated team's orders, newest first. Every order arrives with its line items, transaction ledger, saved card summary and both addresses already embedded, so a single page of results is usually enough to reconcile without follow-up calls.
Required ability
orders:read
Rate limit
60 requests/minute per team

Query parameters

customer_idintegeroptional
Only orders belonging to this customer. This is the `customer_id` returned by the Customers endpoints, not a database id.
Example: 1001
statusstringoptional
Exact match against the order's stored status column. Accepted values: pending, awaiting_payment, completed, paid, shipped, failed, void, partially_void, refunded, partially_refunded, chargeback, partially_chargeback. This filters the stored column, while the status in the response is re-derived from the transaction ledger, so the two can disagree.
Example: completed
created_sincestringoptional
Only orders created at or after this timestamp. The value is passed straight to the database, so send an ISO 8601 timestamp or a plain yyyy-mm-dd date in UTC. There is no validation layer here: an unparseable value produces a 500, not a 422.
Example: 2026-08-01T00:00:00Z
pageintegeroptional
Page number, starting at 1. Anything that is not a positive integer falls back to page 1.
Example: 2
per_pageintegeroptional
Results per page. Defaults to 25 and is capped at 100. There is no lower bound, and out-of-range values are not rejected: see the caveats below.
Example: 50
Caveats
  • The fulfillments key is absent from list results entirely, because this endpoint does not eager-load that relation. Use the single-order endpoint, or the Fulfillments endpoints, when you need shipment data.
  • Pagination links carry only the page parameter. Your customer_id, status and created_since filters are dropped from links.next, so re-send them yourself when walking pages.
  • per_page is capped at 100 but has no floor and is never validated. A value of 0, or any non-numeric string, silently falls back to an internal default of 15 rather than the documented 25; a negative value removes the LIMIT altogether and returns every matching order in a single response.
  • status is recomputed from the order's transaction ledger on every read, so it can differ from the stored value you filtered on. The derived value is one of pending, awaiting_payment, failed, completed, refunded, partially_refunded, void, partially_void, chargeback, partially_chargeback. Externally settled marketplace orders (source gunbroker) are the exception and report their stored status instead, which is how paid and shipped can appear.
  • shipping is the sum of the order's standard shipping and its FFL transfer shipping. The two are not exposed separately.
Requestbash
curl -G https://api.firearmcart.com/v1/orders \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json" \
  -d status=completed \
  -d created_since=2026-08-01T00:00:00Z \
  -d per_page=25
200A page of orders, newest first.
{
  "data": [
    {
      "order_id": 5001,
      "customer_id": 1001,
      "status": "completed",
      "subtotal": 599.97,
      "tax": 49.5,
      "shipping": 19.99,
      "shipping_insurance": 0,
      "hazmat_fee": 0,
      "surcharge": 0,
      "discount": 25,
      "total": 644.46,
      "items": [
        {
          "product_id": 501,
          "variant_id": 1201,
          "name": "Glock 19 Gen 5 9mm Pistol",
          "variant_name": "Finish: Black / Capacity: 15rd",
          "sku": "GLK-PA195S201-BLK",
          "quantity": 1,
          "price": 549.99,
          "subtotal": 549.99,
          "is_cancelled": false,
          "is_recurring": false,
          "properties": null
        },
        {
          "product_id": 733,
          "variant_id": null,
          "name": "Federal American Eagle 9mm 115gr, 50rd",
          "variant_name": null,
          "sku": "FED-AE9DP",
          "quantity": 2,
          "price": 24.99,
          "subtotal": 49.98,
          "is_cancelled": false,
          "is_recurring": false,
          "properties": null
        }
      ],
      "transactions": [
        {
          "transaction_id": "a7c3e9f1-52b8-4d6a-9e04-8b1f6c2d3a90",
          "type": "payment",
          "status": "completed",
          "amount": 644.46,
          "gateway_transaction_id": "11ef9c2a-4d31-4f27-9a10-6c1f0b8e2d55",
          "reference_transaction_id": null,
          "created_at": "2026-08-04T15:22:10+00:00"
        }
      ],
      "payment_method": {
        "brand": "visa",
        "last_four": "4242"
      },
      "shipping_address": {
        "address_id": "6e1d9f27-3c4b-4a85-b1e0-5d8c2f7a94b3",
        "type": "shipping",
        "address_line1": "1200 Market Street",
        "address_line2": "Suite 400",
        "city": "Chattanooga",
        "state": "TN",
        "zip_code": "37402",
        "is_billing": false,
        "is_shipping": true,
        "is_default_billing": false,
        "is_default_shipping": true
      },
      "billing_address": {
        "address_id": "a3f82c50-1d6e-47b9-8e42-9c0d7b3e5f18",
        "type": "billing",
        "address_line1": "88 Riverfront Parkway",
        "address_line2": null,
        "city": "Chattanooga",
        "state": "TN",
        "zip_code": "37402",
        "is_billing": true,
        "is_shipping": false,
        "is_default_billing": true,
        "is_default_shipping": false
      },
      "created_at": "2026-08-04T15:22:08+00:00",
      "updated_at": "2026-08-05T09:14:33+00:00"
    }
  ],
  "links": {
    "first": "https://api.firearmcart.com/v1/orders?page=1",
    "last": "https://api.firearmcart.com/v1/orders?page=2",
    "prev": null,
    "next": "https://api.firearmcart.com/v1/orders?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 2,
    "links": [
      { "url": null, "label": "« Previous", "page": null, "active": false },
      { "url": "https://api.firearmcart.com/v1/orders?page=1", "label": "1", "page": 1, "active": true },
      { "url": "https://api.firearmcart.com/v1/orders?page=2", "label": "2", "page": 2, "active": false },
      { "url": "https://api.firearmcart.com/v1/orders?page=2", "label": "Next »", "page": 2, "active": false }
    ],
    "path": "https://api.firearmcart.com/v1/orders",
    "per_page": 25,
    "to": 25,
    "total": 40
  }
}
403The token is missing the orders:read ability. A team without API access, or with a lapsed subscription, also 403s here, with an error of forbidden or subscription_expired.
{
  "message": "Invalid ability provided."
}
429More than 60 requests in the current minute for this team. Read Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset from the response headers.
{
  "message": "Too Many Attempts."
}

Retrieve an order

GET/v1/orders/{order_id}
Returns a single order by its `order_id`, scoped to the authenticated team. This is the only orders endpoint that includes the fulfillments array and its nested shipments, so it is what you poll for tracking numbers.
Required ability
orders:read
Rate limit
60 requests/minute per team

Path parameters

order_idintegerrequired
The order's `order_id`: the per-store sequential number shown in the dashboard. Not the database primary key.
Example: 5001
Caveats
  • The path segment must be numeric. No route constraint enforces it, so a value such as /v1/orders/abc fails type coercion in the controller and returns a 500 rather than a 404.
  • fulfillment_id, transaction_id and reference_transaction_id are UUIDs. order_id, customer_id, product_id and variant_id are store-scoped numbers. No field on this resource is a database primary key.
  • Addresses expose only street, city, state and ZIP. There is no recipient name, company, country or phone column behind the address resource, so those never appear.
  • An address's type is derived from its role flags rather than stored: an address that is billing-only reports billing and anything else reports shipping. Read is_billing and is_shipping when one address serves both roles.
  • A nested fulfillment's fulfillment_type is the supplier that ships it — the distributor plugin's slug (rsr, chattanooga, lipseys, 2aw, eprolo, mge, printify, sports-south, zanders, kinseys, gun-accessory-supply, davidsons, orion, shipstation) or internal for stock you ship yourself. `mge` and `davidsons` are always warehouse-restock legs (MGE and Davidson's ship to the store, not the customer). It is not a destination flag, so there is no ffl value; whether the shipment routes through a dealer is not exposed on this resource. The sibling service field is a legacy column no production code path writes, so expect null.
  • variant_name is built from the variant's option values (for example "Finish: Black / Capacity: 15rd"), not from the variant's name column. A variant with no options yields an empty string rather than null.
  • An order with no saved card reports payment_method as null, but a missing address does NOT report null. shipping_address and billing_address are wrapped with the single-argument form of whenLoaded, which hands the null relation straight to the address resource, and that resource has no null guard — so an order whose address row is missing or soft-deleted returns a full address object with every field null (and is_billing/is_shipping false) rather than the null you would expect. Test address_line1 for null, not the object itself.
Requestbash
curl https://api.firearmcart.com/v1/orders/5001 \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Accept: application/json"
200The order, with fulfillments and their shipments included.
{
  "data": {
    "order_id": 5001,
    "customer_id": 1001,
    "status": "completed",
    "subtotal": 599.97,
    "tax": 49.5,
    "shipping": 19.99,
    "shipping_insurance": 0,
    "hazmat_fee": 0,
    "surcharge": 0,
    "discount": 25,
    "total": 644.46,
    "items": [
      {
        "product_id": 501,
        "variant_id": 1201,
        "name": "Glock 19 Gen 5 9mm Pistol",
        "variant_name": "Finish: Black / Capacity: 15rd",
        "sku": "GLK-PA195S201-BLK",
        "quantity": 1,
        "price": 549.99,
        "subtotal": 549.99,
        "is_cancelled": false,
        "is_recurring": false,
        "properties": null
      },
      {
        "product_id": 733,
        "variant_id": null,
        "name": "Federal American Eagle 9mm 115gr, 50rd",
        "variant_name": null,
        "sku": "FED-AE9DP",
        "quantity": 2,
        "price": 24.99,
        "subtotal": 49.98,
        "is_cancelled": false,
        "is_recurring": false,
        "properties": null
      }
    ],
    "transactions": [
      {
        "transaction_id": "a7c3e9f1-52b8-4d6a-9e04-8b1f6c2d3a90",
        "type": "payment",
        "status": "completed",
        "amount": 644.46,
        "gateway_transaction_id": "11ef9c2a-4d31-4f27-9a10-6c1f0b8e2d55",
        "reference_transaction_id": null,
        "created_at": "2026-08-04T15:22:10+00:00"
      }
    ],
    "payment_method": {
      "brand": "visa",
      "last_four": "4242"
    },
    "shipping_address": {
      "address_id": "6e1d9f27-3c4b-4a85-b1e0-5d8c2f7a94b3",
      "type": "shipping",
      "address_line1": "1200 Market Street",
      "address_line2": "Suite 400",
      "city": "Chattanooga",
      "state": "TN",
      "zip_code": "37402",
      "is_billing": false,
      "is_shipping": true,
      "is_default_billing": false,
      "is_default_shipping": true
    },
    "billing_address": {
      "address_id": "a3f82c50-1d6e-47b9-8e42-9c0d7b3e5f18",
      "type": "billing",
      "address_line1": "88 Riverfront Parkway",
      "address_line2": null,
      "city": "Chattanooga",
      "state": "TN",
      "zip_code": "37402",
      "is_billing": true,
      "is_shipping": false,
      "is_default_billing": true,
      "is_default_shipping": false
    },
    "fulfillments": [
      {
        "fulfillment_id": "9c2f1a44-73d1-4c8e-9d3e-2f5b8a61c7aa",
        "order_id": 5001,
        "status": "shipped",
        "fulfillment_type": "rsr",
        "service": null,
        "shipments": [
          {
            "tracking_number": "1Z999AA10123456784",
            "carrier": "ups",
            "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
            "shipped_at": "2026-08-05T09:14:31+00:00"
          }
        ],
        "timeline": [],
        "notes": null,
        "processed_at": "2026-08-04T18:03:00+00:00",
        "shipped_at": "2026-08-05T09:14:31+00:00",
        "delivered_at": null,
        "delivery_failed": false,
        "delivery_reason": null,
        "created_at": "2026-08-04T15:22:12+00:00",
        "updated_at": "2026-08-05T09:14:33+00:00"
      }
    ],
    "created_at": "2026-08-04T15:22:08+00:00",
    "updated_at": "2026-08-05T09:14:33+00:00"
  }
}
404No order with that `order_id` belongs to the authenticated team. Another team's order is indistinguishable from one that does not exist.
{
  "error": "not_found",
  "message": "Order not found."
}

Add a post-purchase upsell

POST/v1/orders/{order_id}/upsell
Appends one or more add-on line items to an order that has already been paid, and charges the card on file for just the add-on amount. The charge is recorded as a second transaction on the same order, and the order's subtotal, tax and total are incremented rather than recomputed, so an existing discount or insurance line survives untouched.
Required ability
orders:upsell
Rate limit
30 requests/minute per team

Path parameters

order_idintegerrequired
The `order_id` of the order to extend. It must already carry a completed payment, or be an externally settled marketplace order.
Example: 5001

Body parameters

itemsarray<object>required
The add-on line items. At least one entry is required.
items[].product_idintegerrequired
The product's `product_id`. It must belong to the same store as the order, or the request fails with upsell_invalid.
Example: 733
items[].variant_idintegeroptional
The variant's `variant_id`, which is scoped to the product above. Omit it or send null for a product without variants.
Example: 1201
items[].quantityintegerrequired
Units to add. Minimum 1.
Example: 1
items[].priceintegeroptional
Unit price override in CENTS. Minimum 0. Omit it to charge the variant's price, or the product's price when no variant is given.
Example: 2499
taxintegeroptional
Tax for the add-on, in CENTS. Minimum 0. Omit it and the tax is calculated as POST /v1/orders/{order_id}/upsell/tax returns it. Send it, even as 0, to charge your own amount instead. Add-ons never carry shipping.
Example: 206
idempotency_keystringrequired
Your own unique key for this add-on, up to 255 characters. Replaying it returns the original result instead of charging again. Read the caveats before choosing a key format.
Example: addon_5001_1a2b3c4d
Caveats
  • Units are mixed inside one exchange. You send items[].price and tax in integer cents, the order object comes back in float dollars, and the top-level transaction.amount is in integer cents. Do not reuse one parser for both.
  • Without a tax of your own, the add-on is taxed like the order itself: through the store's tax plugin (Avalara or TaxJar) when one is active, otherwise from the active tax zone covering the order's shipping state, on the add-on's subtotal. Call POST /v1/orders/{order_id}/upsell/tax first to show the shopper that amount.
  • When the tax plugin calculated it, the add-on's tax is recorded with Avalara or TaxJar once charged, as a document of its own beside the order's. Refunding or voiding the add-on's transaction reverses that document only. A tax you send yourself is charged but not recorded with the provider.
  • The idempotency key is looked up across the whole team, not per order: any completed transaction carrying that key wins. Reuse a key from a different order, or from a checkout charge, and you get a 200 with replayed true, no new line items, and a transaction belonging to some other order. Namespace your keys per order.
  • A decline records a failed transaction that stores no idempotency key, so declines are deliberately not covered by the replay guard: retrying a declined add-on with the same key genuinely re-attempts the charge.
  • orders:upsell is not one of the default token abilities. Grant it explicitly when creating the token.
  • The order object in this response omits shipping_address, billing_address and fulfillments, because the reloaded model only eager-loads items, transactions and the payment method. Call the retrieve endpoint when you need them.
  • The card charged is the order's saved payment method, falling back to the customer's most recently created active card. The gateway is the one the original payment settled on, falling back to the team's active card merchant account. If neither can be resolved, the request fails with upsell_invalid.
  • A blacklisted customer or IP is rejected before the gateway is contacted, but that guard throws a non-JSON error the controller cannot classify, so it surfaces as a 500 with error processing_error rather than a 422.
  • Add-on items are tagged with a properties object of { "_upsell": true }, which is how you tell them apart from the original lines.
Requestbash
curl -X POST https://api.firearmcart.com/v1/orders/5001/upsell \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      { "product_id": 733, "quantity": 1, "price": 2499 }
    ],
    "idempotency_key": "addon_5001_1a2b3c4d"
  }'
200The add-on was charged and the line items were added. replayed is true when a previously completed charge with the same idempotency_key was returned instead of a new one.
{
  "success": true,
  "replayed": false,
  "order": {
    "order_id": 5001,
    "customer_id": 1001,
    "status": "completed",
    "subtotal": 574.98,
    "tax": 47.43,
    "shipping": 19.99,
    "shipping_insurance": 0,
    "hazmat_fee": 0,
    "surcharge": 0,
    "discount": 0,
    "total": 642.4,
    "items": [
      {
        "product_id": 501,
        "variant_id": 1201,
        "name": "Glock 19 Gen 5 9mm Pistol",
        "variant_name": "Finish: Black / Capacity: 15rd",
        "sku": "GLK-PA195S201-BLK",
        "quantity": 1,
        "price": 549.99,
        "subtotal": 549.99,
        "is_cancelled": false,
        "is_recurring": false,
        "properties": null
      },
      {
        "product_id": 733,
        "variant_id": null,
        "name": "Federal American Eagle 9mm 115gr, 50rd",
        "variant_name": null,
        "sku": "FED-AE9DP",
        "quantity": 1,
        "price": 24.99,
        "subtotal": 24.99,
        "is_cancelled": false,
        "is_recurring": false,
        "properties": {
          "_upsell": true
        }
      }
    ],
    "transactions": [
      {
        "transaction_id": "a7c3e9f1-52b8-4d6a-9e04-8b1f6c2d3a90",
        "type": "payment",
        "status": "completed",
        "amount": 615.35,
        "gateway_transaction_id": "11ef9c2a-4d31-4f27-9a10-6c1f0b8e2d55",
        "reference_transaction_id": null,
        "created_at": "2026-08-04T15:22:10+00:00"
      },
      {
        "transaction_id": "c1d8f4a2-7e39-4b06-a5c7-9f2e0d6b8a41",
        "type": "payment",
        "status": "completed",
        "amount": 27.05,
        "gateway_transaction_id": "11ef9c2a-77b0-4a19-8c31-2f7e5d9a1b04",
        "reference_transaction_id": null,
        "created_at": "2026-08-04T15:41:02+00:00"
      }
    ],
    "payment_method": {
      "brand": "visa",
      "last_four": "4242"
    },
    "created_at": "2026-08-04T15:22:08+00:00",
    "updated_at": "2026-08-04T15:41:02+00:00"
  },
  "transaction": {
    "transaction_id": "c1d8f4a2-7e39-4b06-a5c7-9f2e0d6b8a41",
    "gateway_transaction_id": "11ef9c2a-77b0-4a19-8c31-2f7e5d9a1b04",
    "amount": 2705,
    "status": "completed"
  }
}
422Four different failures share this status, told apart by the error field: payment_declined (shown here, with a details object carrying the gateway codes), order_not_paid when the order has no completed payment, upsell_invalid when a product or variant is not found or the order has no card or merchant account to charge, and a stock validation body of message plus errors when the request itself is malformed.
{
  "success": false,
  "error": "payment_declined",
  "message": "Insufficient funds",
  "details": {
    "response_code": "051",
    "response_message": "Insufficient funds"
  }
}
409Another add-on for this order and idempotency_key is mid-flight and the 10-second lock wait expired. Retry.
{
  "success": false,
  "error": "in_progress",
  "message": "Another add-on for this order is currently processing. Please retry."
}
404No order with that `order_id` belongs to the authenticated team. Note that the error code differs from the one the retrieve endpoint returns.
{
  "success": false,
  "error": "order_not_found",
  "message": "Order not found."
}

Calculate an upsell's tax

POST/v1/orders/{order_id}/upsell/tax
Calculates the tax on add-on items for a paid order without charging them. Send the items you will send to POST /v1/orders/{order_id}/upsell and you get back the tax that endpoint charges when you send no tax of your own, worked out at the order's ship-to address for its customer.
Required ability
orders:upsell
Rate limit
60 requests/minute per team

Path parameters

order_idintegerrequired
The `order_id` of the order the add-on is for. It must already carry a completed payment, or be an externally settled marketplace order, as the upsell endpoint requires.
Example: 5001

Body parameters

itemsarray<object>required
The add-on line items. At least one entry is required.
items[].product_idintegerrequired
The product's `product_id`. It must belong to the same store as the order, or the request fails with upsell_invalid.
Example: 733
items[].variant_idintegeroptional
The variant's `variant_id`, which is scoped to the product above. Omit it or send null for a product without variants.
Example: 1201
items[].quantityintegerrequired
Units. Minimum 1.
Example: 1
items[].priceintegeroptional
Unit price override in CENTS. Minimum 0. Omit it to use the variant's price, or the product's price when no variant is given.
Example: 2499
Caveats
  • Every amount in the response is integer cents, the unit the upsell endpoint takes, not the float dollars orders come back in. shipping is always 0, because add-ons carry none, and total is exactly what the upsell charges: add-ons are never surcharged.
  • source says where the tax came from: avalara or taxjar for the store's tax plugin, tax_zone for a manual tax zone (tax_zone then names it, with its rate), or none when no active zone covers the state. A store with a tax plugin reports tax_zone only when the plugin call failed and the zones stood in.
  • The add-on is taxed at the order's shipping address, for the order's customer. With a tax plugin, an exemption on that shipping address applies, or else the customer's own. A local pickup order is taxed at the store's address instead, as checkout taxed the order.
  • Nothing is charged and nothing is added to the order, so there is no idempotency_key. The upsell itself calculates the same tax when you send none, so don't send this one back: an add-on charged with a tax you send is not recorded with the tax plugin.
  • Unlike the upsell endpoint, this one counts against the standard 60 requests/minute limit only, not the 30/minute payments limit.
Requestbash
curl -X POST https://api.firearmcart.com/v1/orders/5001/upsell/tax \
  -H "Authorization: Bearer $FIREARMCART_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "items": [
      { "product_id": 733, "quantity": 1, "price": 2499 }
    ]
  }'
200The add-on's tax, here from the store's Texas tax zone. Every amount is integer cents.
{
  "data": {
    "source": "tax_zone",
    "subtotal": 2499,
    "shipping": 0,
    "tax": 206,
    "total": 2705,
    "tax_zone": {
      "zone_id": 1,
      "name": "Texas Sales Tax",
      "rate": 0.0825
    },
    "items": [
      {
        "product_id": 733,
        "variant_id": null,
        "quantity": 1,
        "price": 2499,
        "subtotal": 2499
      }
    ]
  }
}
422Three failures share this status, told apart by the error field: order_not_paid when the order has no completed payment, upsell_invalid (shown here) when a product or variant is not found, and a stock validation body of message plus errors when the request itself is malformed.
{
  "success": false,
  "error": "upsell_invalid",
  "message": "Product with ID 999 not found."
}
404No order with that `order_id` belongs to the authenticated team, or the `order_id` is not a number.
{
  "success": false,
  "error": "order_not_found",
  "message": "Order not found."
}
Navigation

Type to search…

↑↓ navigate↵ selectEsc close