Skip to content
Stashtab Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Redemption packing exceptions

Find, read and answer cards that the warehouse cannot pack as ordered, and follow the Test walkthrough.

A packing exception occurs when the warehouse cannot pack a redemption card as ordered. The card can be missing, damaged or in a different condition. The warehouse holds the whole order and records each affected card. For each card, the player chooses to accept a replacement card or to remove the card. Your application reads the exception, asks the player, and sends the answer to Vault.

This page uses these terms:

  • Unit: one physical copy of a card on an order line. Two copies of the same card are two units with different IDs.
  • Offer: what the warehouse offers for one unit. It is a replacement card, or no offer. When there is no offer, removal is the only answer.
  • Hold: the order cannot ship while its packing exception is held.

Every HTTP operation on this page has the same MCP tool. The MCP tool catalog has the matching schemas.

Step HTTP MCP tool
Read up to 20 orders POST /v1/organizations/{orgId}/orders/batch orders_batch_get
Read one order GET /v1/organizations/{orgId}/orders/{orderId} orders_get
Answer one unit POST /v1/organizations/{orgId}/orders/{orderId}/packing-exception/units/{unitId}/answer orders_packing_exception_answer

How a packing exception works

  1. The warehouse finds a card that it cannot pack as ordered. The parcel is still under warehouse control.
  2. Warehouse staff record the exception. The order is held. Each affected unit gets an offer and a response deadline 168 hours (7 days) later.
  3. Your application finds the exception on its next order read.
  4. The player answers each unit. Your application sends each answer.
  5. Vault applies each answer on its own. An applied removal is final, so you can restore the token for that card while other units wait.
  6. A unit with no answer at its deadline is removed automatically.
  7. When every unit is applied and any purchased label is reconciled, the hold ends. The remaining cards ship together. If no card remains, Vault cancels the order.

There is no notification for packing exceptions. Polling is the integration path.

Find packing exceptions by polling

Read every redemption that has not shipped at least once an hour. Use the batch read for up to 20 order IDs, or the single order read. An available redemption in the result includes packingException:

  • null: no card on the order was held.
  • An object: the packing exception. Its status is held or resolved.

Ordinary orders do not include the field. Order lists do not include it. Read the order to see the exception.

Read access is enough to poll. A Viewer or a read-only organization key can read the exception. The polling guide explains batch results, missing and unavailable items, and retry timing.

Read a packing exception

The exception is at data.packingException in an HTTP order read, and at order.packingException in each available batch item. This example has two copies of the same card on line 0. The first copy has an applied answer. The second copy waits for an answer. All IDs and amounts are synthetic.

{
  "estimate": {
    "amount": "12.00",
    "asOf": "2026-11-18T12:05:00.000Z",
    "basis": "estimate",
    "complete": false,
    "components": [
      { "amount": "8.00", "code": "shipping" },
      { "amount": "4.00", "code": "fulfillment" },
      { "amount": "0.00", "code": "insurance" }
    ],
    "currency": "USD",
    "revision": 1
  },
  "id": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
  "recordedAt": "2026-11-18T09:00:00.000Z",
  "resolvedAt": null,
  "revision": 3,
  "status": "held",
  "units": [
    {
      "decision": {
        "answer": "accept_offer",
        "decidedAt": "2026-11-18T12:04:00.000Z",
        "offerRevision": 2,
        "operationId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "source": "answer"
      },
      "foundCondition": "lp",
      "id": "4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d",
      "lineIndex": 0,
      "offer": {
        "condition": "nm",
        "id": "0b6f5a8e-3c1d-4e2f-9a7b-5c4d3e2f1a0b",
        "kind": "replacement",
        "product": "DEMO-CARD-NM",
        "readableAt": "2026-11-18T10:00:00.000Z",
        "responseDeadlineAt": "2026-11-25T10:00:00.000Z",
        "revision": 2
      },
      "ordered": { "condition": "nm", "product": "Demo card", "sku": "DEMO-CARD-NM" },
      "outcome": "applied",
      "packCardOrdinal": null,
      "reason": "condition_mismatch",
      "responseDeadlineAt": "2026-11-25T10:00:00.000Z",
      "unitIndex": 0
    },
    {
      "decision": null,
      "foundCondition": null,
      "id": "5b4c3d2e-1f0a-4b9c-8d7e-6f5a4b3c2d1e",
      "lineIndex": 0,
      "offer": {
        "condition": "nm",
        "id": "6c5d4e3f-2a1b-4c0d-9e8f-7a6b5c4d3e2f",
        "kind": "replacement",
        "product": "DEMO-CARD-NM",
        "readableAt": "2026-11-18T09:00:00.000Z",
        "responseDeadlineAt": "2026-11-25T09:00:00.000Z",
        "revision": 1
      },
      "ordered": { "condition": "nm", "product": "Demo card", "sku": "DEMO-CARD-NM" },
      "outcome": "awaiting_answer",
      "packCardOrdinal": null,
      "reason": "missing",
      "responseDeadlineAt": "2026-11-25T09:00:00.000Z",
      "unitIndex": 1
    }
  ]
}

Exception fields

Field Meaning
id The packing exception. One order has at most one exception.
status held keeps the order from shipping. resolved ends the hold.
recordedAt, resolvedAt When the warehouse recorded the exception, and when it was resolved.
revision Increases when the exception changes. Use it to detect a change between reads.
units One entry for each affected unit. Unaffected cards are not in this list.
estimate The current revised customer estimate, or null before Vault calculates one. See estimates and charges.

Unit fields

Field Meaning
id The stable unit ID. Send it as unitId when you answer.
lineIndex, unitIndex The zero-based order line and the zero-based copy on that line.
packCardOrdinal The card position in the published pack, when known. Otherwise null.
ordered The ordered product name, SKU and condition.
reason condition_mismatch, missing or damaged.
foundCondition The condition that the warehouse found: nm, lp, mp, hp, dmg or no_damage_found. null for a missing card.
offer The current offer. See the next table.
responseDeadlineAt The deadline for this unit. It is the same as offer.responseDeadlineAt.
decision null until the unit has a decision. Then answer, source, offerRevision, decidedAt and operationId.
outcome Where the decision is. See outcomes.

Offer fields:

Field Meaning
id, revision Copy both into your answer. A new offer gets a new ID and a higher revision.
kind replacement offers one reserved card. no_offer means that removal is the only answer.
product, condition The SKU of the offered replacement card, and its condition. null for no_offer.
readableAt When the offer became readable through the API.
responseDeadlineAt readableAt plus 168 hours.

Decision source is answer for your answer and deadline_default for an automatic removal at the deadline. The value warehouse is reserved for a decision that warehouse staff record on your instruction. Vault does not create it today. operationId is the operation ID of your answer. It is null for the other two sources.

Outcomes

outcome Meaning Restore a token?
awaiting_answer The unit has no decision. No
received Vault stored the decision. It is not applied yet. No
pending The warehouse is applying the decision. The result is not known yet. No
applied The decision is final and its effect is confirmed. Yes, for remove_card
refused Vault did not apply the decision. The order stays held, and the warehouse recovers it. No

Confirmed removals

A unit with decision.answer: "remove_card" and outcome: "applied" is a confirmed removal. That card will not ship. This is the evidence to restore the token for that card. The other units can still wait for answers.

A received or pending removal is not confirmed. Do not restore a token for it. A removal by deadline_default is confirmed in the same way when its outcome is applied.

Current order contents

The order items keep the content of the order as it was created. To get the current contents, apply each unit with outcome: "applied" to its line:

  • remove_card: subtract one card from line lineIndex.
  • accept_offer: that copy ships as the card with SKU offer.product, in offer.condition.

Units that are not applied still count as ordered. Use your stored unitIndex values to keep each copy separate.

Estimates, charges and invoices

Vault recalculates the changed order under your agreed rates and the current shipping requirements. estimate shows the result:

Field Meaning
basis Always estimate. It is not a charge.
amount The estimated total, as a decimal string. null means that Vault does not know the amount.
complete true only when every affected unit is applied and Vault knows the amount. false while any unit is not applied: Vault prices that card as ordered, so the estimate is provisional. Also false when amount is null.
components Each part of the estimate: shipping, fulfillment, insurance, and one fee:<name> for each agreed fee. A component amount can also be null.
currency, revision, asOf The currency, the estimate revision and when Vault calculated it.

An unknown amount is always null. It is never 0. A higher estimate does not need an approval from you or the player, and the order continues. There is no price timer and no cancellation because a price increased.

Three different amounts apply to a redemption:

Amount Where you read it What it means
Estimate packingException.estimate The expected cost of the changed order. Vault never charges an estimate.
Actual charge Invoice lines A charge from actual warehouse work and actual carrier cost, under your rate card.
Final invoice Invoices The issued invoice that contains those charges.

The warehouse pays the carrier and fulfillment costs first. Then Vault bills your organization through your ordinary invoices. A later correction from a carrier or source uses the ordinary adjustment and credit lines.

This is the agreed billing policy. It applies when Live packing exceptions are available. A label void request is not a refund, and only a confirmed carrier refund becomes a credit. A replay or a repeated settlement never adds a second charge. Test settlement writes no billing rows, so Test creates no charges, credits or invoices.

Answer a unit

Send one answer for each unit. Copy offerId and offerRevision from the unit’s current offer in a fresh order read. Save the submissionKey with the request before you send it.

The HTTP body:

{
  "answer": "accept_offer",
  "offerId": "0b6f5a8e-3c1d-4e2f-9a7b-5c4d3e2f1a0b",
  "offerRevision": 2,
  "submissionKey": "packing-answer-demo-1"
}
answer Effect
accept_offer The replacement card in the current offer replaces this unit. Only for kind: "replacement".
remove_card This unit is removed from the order. Any reserved replacement card is released.

An answer is final. The API cannot change it. If the player needs a correction, contact Stashtab support.

Members and higher roles can answer. An organization key needs Read/write permission. A Viewer or a read-only key gets 403 forbidden. A unit in another organization or mode gets 404 not_found.

A successful answer returns 200:

{
  "data": {
    "answer": {
      "answer": "accept_offer",
      "answeredAt": "2026-11-18T12:04:00.000Z",
      "id": "7e6d5c4b-3a29-4180-9f7e-6d5c4b3a2918",
      "offerId": "0b6f5a8e-3c1d-4e2f-9a7b-5c4d3e2f1a0b",
      "offerRevision": 2
    },
    "operationId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "outcome": "applied",
    "unit": {
      "decision": {
        "answer": "accept_offer",
        "decidedAt": "2026-11-18T12:04:00.000Z",
        "offerRevision": 2,
        "operationId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
        "source": "answer"
      },
      "foundCondition": "lp",
      "id": "4a3b2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d",
      "lineIndex": 0,
      "offer": {
        "condition": "nm",
        "id": "0b6f5a8e-3c1d-4e2f-9a7b-5c4d3e2f1a0b",
        "kind": "replacement",
        "product": "DEMO-CARD-NM",
        "readableAt": "2026-11-18T10:00:00.000Z",
        "responseDeadlineAt": "2026-11-25T10:00:00.000Z",
        "revision": 2
      },
      "ordered": { "condition": "nm", "product": "Demo card", "sku": "DEMO-CARD-NM" },
      "outcome": "applied",
      "packCardOrdinal": null,
      "reason": "condition_mismatch",
      "responseDeadlineAt": "2026-11-25T10:00:00.000Z",
      "unitIndex": 0
    }
  },
  "meta": { "requestId": "req_example" }
}

outcome has the same meaning as the unit outcome. In Test, Vault applies the answer immediately, so the response usually shows applied. If that step fails, the response shows received, and a scheduled run applies the answer later. In Live, the answer stays received for now.

Refusals

Every refusal is 409 state_conflict. The reason is in error.fields[0].code. A refusal changes nothing.

Code Path Cause What to do
stale_offer offerRevision The warehouse replaced the offer after your read. Read the order again and ask the player about the new offer.
no_current_offer answer You sent accept_offer, but the current offer is no_offer. Ask the player again. Removal is the only answer.
already_decided unitId The unit already has a decision. Read the order for the decision.
response_window_closed unitId The deadline passed, and the default removal is not applied yet. Read the order. The unit is removed by default.
exception_resolved orderId The exception is already resolved. Read the order.
submission_conflict submissionKey You used this key before with different content. Send the new answer with a new key.
{
  "error": {
    "code": "state_conflict",
    "message": "The offer changed since it was read. Reload the order and answer the current offer. Nothing was changed.",
    "fields": [
      {
        "code": "stale_offer",
        "message": "The offer changed since it was read. Reload the order and answer the current offer. Nothing was changed.",
        "path": "offerRevision"
      }
    ],
    "operationId": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b"
  },
  "meta": { "requestId": "req_example" }
}

An offerId that is not a UUID gets 400 validation_error with code invalid_offer. An offerId that is a UUID but is not the current offer of the unit gets 409 state_conflict with code stale_offer. An organization without an active Test workspace gets warehouse_not_ready in Test.

After the deadline default is applied, the unit has a decision. Then every answer gets already_decided. The code response_window_closed occurs only between the deadline and the run that applies the default.

Retries and lost responses

Each submission key belongs to one answer. Vault never applies the same answer twice.

  • Exact replay. The same key and the same body return the original answer.id, answeredAt, offerRevision and operationId. This is true after the offer or the outcome changed. outcome shows the current state. A replay never answers a newer offer.
  • Replay of a refusal. The same key and body return the same refusal and the same operationId.
  • Changed content. The same key with a different body gets submission_conflict.
  • Lost response. Send the same body with the same key again. Or read the order: the unit decision.operationId is the operationId of your answer.
  • Request still running. A retry during the first request gets 409 state_conflict with the operationId. Retry later with the same key.

Do not change the submission key to retry. A new key with the same answer gets already_decided after the first answer is stored.

Deadlines and offer changes

Each unit has its own deadline. The deadline is readableAt plus 168 hours. It does not change when you read the order or send a replay.

At the deadline, a unit with no decision is removed automatically. Its decision shows answer: "remove_card" and source: "deadline_default". Vault checks for due units every 5 minutes, so the default can occur a few minutes after the deadline.

The warehouse can change an offer while the unit has no decision:

  • Replacement. A new replacement card gives a new offer ID, a higher revision and a new 168-hour deadline for that unit only. Other units keep their deadlines. An answer to the old revision gets stale_offer.
  • Withdrawal. The offer becomes no_offer with a higher revision. The unit keeps its existing deadline. An accept_offer answer gets no_current_offer.

After a unit has a decision, the warehouse cannot change its offer.

What the hold blocks

While status is held:

  • The order does not ship.
  • Release and held-order edits are refused with code packing_exception_held.
  • The one-hour redemption timer does not release the order.

You can still cancel a redemption inside its one-hour cancellation window. Cancellation releases every reserved replacement card and resolves the exception.

Purchased labels

The warehouse can buy the outbound label before it packs the cards. A label or a tracking number does not mean that the parcel left the warehouse. The warehouse can record an exception while the parcel is still under warehouse control.

When a label exists, the hold also waits for label reconciliation. The warehouse compares the label with the remaining cards:

  • If the label still fits, the warehouse keeps it.
  • If the label does not fit, the warehouse voids it and buys one replacement.
  • If no card remains, the warehouse voids the unused label.

A change of recipient, service, card count, declared value or international contents can make a label not fit. Fewer cards on a domestic parcel keep the label.

Your order read does not show the label state. While reconciliation continues, every unit can be applied but status stays held. If a void or a purchase result is unknown, the order stays held until the warehouse reads the result. The warehouse never buys a second usable label for the same parcel. After the carrier has the parcel, packing exceptions do not apply. Contact Stashtab support.

Test walkthrough

This walkthrough shows the complete flow in Test. In Test, an organization Owner or Admin records the packing exception in the Vault console. This simulates the warehouse step. Only the warehouse can replace an offer, so you ask Stashtab support to do that step for you.

Before you start

  • Use a Test API key with Read/write permission and your organization ID. The Test orders guide explains how to get them. Keep the key in your secret store. Do not send it to support.
  • Set VAULT_BASE_URL, ORG_ID and VAULT_ORGANIZATION_API_KEY as in that guide.
  • Keep a log of each request, its submission key, the response meta.requestId and the operationId.
  • Have an organization Owner or Admin who can sign in to the Vault console in Test, and in-stock Test cards for the replacement offers.

1. Create a Test redemption

Create a Test redemption with explicit lines, as in the redemption walkthrough. Use two lines:

  • Line 0: one raw card with quantity: 2. The two copies become two units.
  • Line 1: a different card with quantity: 1. This card is not affected.

Use a United States recipient. Only the purchased-label scenario for a label replacement needs a recipient outside the United States. Save the order ID as ORDER_ID. After the one-hour cancellation window, read the order and release it.

2. Record the exception in the Vault console

Sign in to the Vault console as an organization Owner or Admin, and switch to Test mode. Open Orders, then open the order from step 1. In Order controls, choose Record packing exception. For each affected card, the form sets a reason and an offer. The console counts lines and copies from 1, so line 0 from step 1 shows as line 1:

  • Line 1, copy 1 (lineIndex 0, unitIndex 0): reason Condition mismatch, condition found LP, and an in-stock Test replacement card.
  • Line 1, copy 2 (lineIndex 0, unitIndex 1): reason Missing, and an in-stock Test replacement card.

Do not choose line 2 (lineIndex 1). Select Record exception. Vault holds the order and starts a 168-hour response deadline for each card, as it does for a warehouse recording.

The action is available only on a Test redemption that has not shipped, is not canceled and has no held exception. On a shipped, canceled or already held Test redemption it is disabled, and the console shows the reason. Other Test orders and Live orders do not have this action.

Then ask Stashtab support in your shared support channel to replace the offer for copy 0 (unitIndex 0, shown as copy 1 in the console) when you say that you read revision 1. Send your organization ID, the word Test and the order ID. Do not include credentials or player details.

3. Read the exception

Read the order:

curl --fail-with-body \
  --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders/$ORDER_ID"

Expected result:

  • data.packingException.status is held.
  • units has two entries for line 0, with different id values.
  • Line 1 is not in units.
  • Each unit has offer.kind: "replacement", offer.revision: 1, outcome: "awaiting_answer" and a responseDeadlineAt 168 hours after offer.readableAt.

Save the id, offer.id and offer.revision of each unit. Set UNIT_0 and UNIT_1 to the two unit IDs. Then tell support that you read revision 1.

4. Send a stale answer

After support replaces the offer for copy 0, send an answer for the old offer:

curl --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"answer":"accept_offer","offerId":"<copy 0 offer ID from step 3>","offerRevision":1,"submissionKey":"walkthrough-stale-1"}' \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders/$ORDER_ID/packing-exception/units/$UNIT_0/answer"

Expected result: 409, error.code is state_conflict and error.fields[0].code is stale_offer. Read the order again. Copy 0 has a new offer.id, offer.revision: 2 and a new responseDeadlineAt. Copy 1 keeps its deadline. No decision is recorded.

5. Accept the new offer for copy 0

Send the answer with the new offer ID and revision 2:

curl --fail-with-body \
  --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"answer":"accept_offer","offerId":"<copy 0 offer ID from step 4>","offerRevision":2,"submissionKey":"walkthrough-accept-1"}' \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders/$ORDER_ID/packing-exception/units/$UNIT_0/answer"

Expected result: 200. data.outcome is applied. If it is received, read the order again after a few minutes. data.unit.decision.source is answer. Save data.operationId. packingException.status stays held because copy 1 has no answer. The estimate is provisional while copy 1 waits, and its complete is false.

6. Replay the same answer

Send the request from step 5 again with the same key and body.

Expected result: 200 with the same answer.id, answeredAt and operationId as step 5. No second answer is recorded. Then send the same key with "answer":"remove_card". Expected result: 409 with submission_conflict.

7. Remove copy 1

curl --fail-with-body \
  --header "Authorization: Bearer $VAULT_ORGANIZATION_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"answer":"remove_card","offerId":"<copy 1 offer ID from step 3>","offerRevision":1,"submissionKey":"walkthrough-remove-1"}' \
  "$VAULT_BASE_URL/v1/organizations/$ORG_ID/orders/$ORDER_ID/packing-exception/units/$UNIT_1/answer"

Expected result: 200 and data.outcome is applied.

8. Read the confirmed changes

Read the order again. Expected result:

  • Copy 0: decision.answer is accept_offer, outcome is applied.
  • Copy 1: decision.answer is remove_card, outcome is applied. This is the confirmed removal. In your platform, restore the token for that card now.
  • status is resolved and resolvedAt is set.
  • The current contents are one copy of the line 0 card as the replacement, plus the line 1 card.
  • estimate has a new revision and asOf. Every unit is applied, so complete is true when amount is not null. If amount is null, complete is false.

Compare estimate.amount with the amount from your original quote. The amount can be higher or lower. No step asks for a price approval, and the order continues in both cases.

9. Continue the remaining cards

An Owner or Admin opens Test actions in Vault and simulates the shipment, as in the Test orders guide. Expected result: the order ships with a TEST- tracking number.

To see the hold, repeat steps 1 to 3 on a second order. Then try to simulate its shipment before you answer. Expected result: the simulator does not ship the order while the exception is held.

Purchased-label scenario

Use a new Test redemption from step 1, released. To see a replaced label, use a recipient outside the United States. Instead of recording in the console in step 2, ask Stashtab support to record the exception with a purchased label. The console form cannot record a label. Then answer the units as in steps 5 and 7.

Expected result:

  • After the last answer, every unit is applied, but status stays held.
  • Simulated shipment does not ship the order.
  • After support reconciles the label, status is resolved. Then the shipment simulation succeeds.

Ask support to tell you the label result. The result depends on your choices:

Your choices Label result
United States recipient, remove one card The label is kept.
Recipient outside the United States, accept a replacement card The label is voided and one replacement label is bought.
Remove every card The unused label is voided, and Vault cancels the order.

Test labels are synthetic. Test buys no postage and requests no refund.

Seven-day default

Use a new Test redemption from step 1. Record one unit as in step 2, and do not answer it. Save its responseDeadlineAt.

Test uses real time. There is no Test clock, and support cannot move the deadline forward. The default occurs at most a few minutes after responseDeadlineAt, which is 168 hours after readableAt. Read the order after that time. Expected result:

  • decision.answer is remove_card.
  • decision.source is deadline_default and decision.operationId is null.
  • outcome is applied.

An answer after Vault applies the default gets already_decided. An answer in the few minutes between the deadline and the default gets response_window_closed.

Clean up

All objects in this walkthrough are in your current Test workspace. They are synthetic and never become Live data.

  • Inside the one-hour window, you can cancel an unused Test redemption. This releases its reserved replacement cards.
  • An Owner can reset the Test workspace. A reset removes active Test orders and starts a new Test generation. Old order IDs then return not_found. Coordinate a reset with your team. Do not reset to retry an unknown answer.
  • Keep Test and Live keys, IDs and logs separate.

What Test shows

The walkthrough shows the API contract, the replay rules and the order states in Test. It does not show a Live warehouse effect, a carrier label, a carrier handoff, a refund, an invoice or a token action.

Was this page helpful?