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 |
- Reference: Read orders in a batch, Read an order, Answer a packing exception.
How a packing exception works
- The warehouse finds a card that it cannot pack as ordered. The parcel is still under warehouse control.
- Warehouse staff record the exception. The order is held. Each affected unit gets an offer and a response deadline 168 hours (7 days) later.
- Your application finds the exception on its next order read.
- The player answers each unit. Your application sends each answer.
- 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.
- A unit with no answer at its deadline is removed automatically.
- 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
statusisheldorresolved.
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 linelineIndex.accept_offer: that copy ships as the card with SKUoffer.product, inoffer.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,offerRevisionandoperationId. This is true after the offer or the outcome changed.outcomeshows 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.operationIdis theoperationIdof your answer. - Request still running. A retry during the first request gets
409 state_conflictwith theoperationId. 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_offerwith a higher revision. The unit keeps its existing deadline. Anaccept_offeranswer getsno_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_IDandVAULT_ORGANIZATION_API_KEYas in that guide. - Keep a log of each request, its submission key, the response
meta.requestIdand theoperationId. - 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 (
lineIndex0,unitIndex0): reason Condition mismatch, condition found LP, and an in-stock Test replacement card. - Line 1, copy 2 (
lineIndex0,unitIndex1): 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.statusisheld.unitshas two entries for line 0, with differentidvalues.- Line 1 is not in
units. - Each unit has
offer.kind: "replacement",offer.revision: 1,outcome: "awaiting_answer"and aresponseDeadlineAt168 hours afteroffer.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.answerisaccept_offer,outcomeisapplied. - Copy 1:
decision.answerisremove_card,outcomeisapplied. This is the confirmed removal. In your platform, restore the token for that card now. statusisresolvedandresolvedAtis set.- The current contents are one copy of the line 0 card as the replacement, plus the line 1 card.
estimatehas a newrevisionandasOf. Every unit isapplied, socompleteistruewhenamountis notnull. Ifamountisnull,completeisfalse.
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, butstatusstaysheld. - Simulated shipment does not ship the order.
- After support reconciles the label,
statusisresolved. 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.answerisremove_card.decision.sourceisdeadline_defaultanddecision.operationIdisnull.outcomeisapplied.
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.