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

Create a held redemption order

Redemption lines can set declaredUnitValue.amount in USD per unit. Omitted values keep the product-default behavior. A unit value multiplies by quantity for the line total. Values belong to this order and do not change catalog defaults, sale prices, insurance amounts or delivery confirmation. A changed value requires a fresh review and quote. The same submission key with changed values conflicts. Provider readback must retain the exact declarations without appended catalog defaults. Create a redemption from exact catalog products, recorded conditions and quantities through the shared order-creation module. A deliveryConfirmation request must match the priced shippingQuote selection. Omit the top-level value to carry the selection unchanged. Changed confirmation conflicts with the original intent; it never shortens the hold or permits another uncertain purchase. For cards from a published pack, call previewPackRedemption and use its exact product IDs, conditions and quantities as explicit lines for all or selected cards. The optional pack input uses the returned frozen pack revision and digest and preserves source identities for replay. New redemptions start On hold. The creation receipt carries a server-owned cancellation.deadlineAt exactly one hour after confirmed creation; eligible describes that creation-time fact, and replay never extends the deadline. Preview those products and quantities with orderKind: redemption to validate the exact destination and obtain fulfillmentSource, then quote the same recipient and physical source. Creation independently requires a positive postal result in Test and Live. Pass the exact selected shippingQuote, fulfillmentSource, requestedShippingService and requestedShippingServiceReview unchanged. Vault revalidates the recipient, stock, source, parcel, eligible service and current rates before sending; changed inputs or prices require a fresh quote and selection. Quotes are estimates and do not lock a carrier price or buy a label. An exact submission-key replay returns its original receipt, changed intent conflicts, and an unknown provider result is observed rather than sent again. Current write-capable organization keys may use this customer operation. Vault Test supports explicit configured raw-condition and sealed-item lines using isolated exact stock reservation and synthetic correlation. Exact replay does not reserve again; timely cancellation restores the commitment once. Test release is manual after one hour, and no hosted timer or physical warehouse guarantee is established. Frozen pack creation and exact-slab selections remain unavailable in Vault Test; use explicit lines returned by a configured Test pack preview. The success example illustrates a Live business-mode confirmed order shape. Its legacy TEST adapter label names an unverified external partner correlation only. It does not identify Vault Test mode or the provider environment, prove hosted activation, or establish provider or physical acceptance. The static example is not evidence of a live provider effect. Native protocol authority remains separate.

POST/v1/organizations/{orgId}/orders/redemptions
Authorization
AuthorizationBasic auth · headerrequired

Registered confidential integration credentials. Keep the secret server-side.

or
CookieAPI key · headerrequired

Console-managed Vault session cookie; secure cookie naming may vary by environment.

or
AuthorizationBearer token (Vault TEST service token) · headerrequired

Customer- and resource-bound service grant, rechecked on every call. Existing Live opening-feed authority remains narrow; ordinary Test business requests refuse until shared Test composition is available.

or
AuthorizationBearer token (Vault organization API key) · headerrequired

Organization-owned credential with immutable mode and Read-only or Read/write permissions. Only explicitly declared ordinary customer operations accept it. Test business access refuses until shared Test composition is available; no staff, team, key-management or protocol authority is granted.

Path parameters
orgIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
Request body
requiredapplication/json
deliveryConfirmationstring
Allowed:nonedeliverysignatureadult_signaturedirect_signature
customerLabelstring | null
Show properties
Any of:
string
string
null
null
fulfillmentSourceobject
Show properties
Any of:
object
configurationRevisionstringrequired
matches ^[1-9][0-9]*$
sourceSignaturestringrequired
matches ^[0-9a-f]{64}$
physicalOriginEquivalenceRefstringrequired
min length 1 · max length 200
v1WarehouseIdintegerrequired
max 9007199254740991
object
modestringrequired
configurationRevisionstringrequired
matches ^[1-9][0-9]*$
sourceSignaturestringrequired
matches ^[0-9a-f]{64}$
physicalOriginEquivalenceRefstringrequired
min length 1 · max length 200
linesobject[]
max items 100
Show properties
Array of object
conditionstring | nullrequired
Show properties
Any of:
string
string
null
null
declaredUnitValueobject
Show properties
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
productIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
quantityintegerrequired
min 1 · max 100000
skustring
min length 1 · max length 200
orderKeystringrequired
min length 1 · max length 128
orderNumberstring
min length 1 · max length 100
packobject
Show properties
cardOrdinalsinteger[]
min items 1 · max items 10
declaredUnitValuesobject[]
min items 1 · max items 10
Show properties
Array of object
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
productIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
deploymentRefstringrequired
min length 1 · max length 200
packReferencestringrequired
matches ^0x[0-9a-f]{64}$
sourceContentRevisionintegerrequired
max 9007199254740991
sourceDigeststringrequired
matches ^[0-9a-f]{64}$
recipientobjectrequired
Show properties
addressLine1string | null
Show properties
Any of:
string
string
null
null
addressLine2string | null
Show properties
Any of:
string
string
null
null
addressLine3string | null
Show properties
Any of:
string
string
null
null
citystring | null
Show properties
Any of:
string
string
null
null
companystring | null
Show properties
Any of:
string
string
null
null
companyNamestring | null
Show properties
Any of:
string
string
null
null
contactNamestring | null
Show properties
Any of:
string
string
null
null
countrystring | null
Show properties
Any of:
string
string
null
null
countryCodestring | null
Show properties
Any of:
string
string
null
null
emailstring | null
Show properties
Any of:
string
string
null
null
namestring | null
Show properties
Any of:
string
string
null
null
phonestring | null
Show properties
Any of:
string
string
null
null
postalCodestring | null
Show properties
Any of:
string
string
null
null
regionstring | null
Show properties
Any of:
string
string
null
null
statestring | null
Show properties
Any of:
string
string
null
null
street1string | null
Show properties
Any of:
string
string
null
null
street2string | null
Show properties
Any of:
string
string
null
null
street3string | null
Show properties
Any of:
string
string
null
null
redemptionReferencestringrequired
min length 1 · max length 200
requestedShippingServicestring
max length 200
requestedShippingServiceReviewstring
matches ^[0-9a-f]{64}$
shippingQuoteobject
Show properties
deliveryConfirmationstring
Allowed:nonedeliverysignatureadult_signaturedirect_signature
insuranceobject
Show properties
One of:
object
kindstringrequired
object
kindstringrequired
packagesobject[]required
min items 1 · max items 100
Show properties
Array of object
amountstringrequired
matches ^(0|[1-9]\d{0,8})(\.\d{1,4})?$
currencystringrequired
matches ^[A-Z]{3}$
providerstringrequired
Allowed:carrierparcelguardshipsurancexcover
reviewstringrequired
matches ^[0-9a-f]{64}$
requestedShippingServicestringrequired
min length 1 · max length 200
requestedShippingServiceReviewstringrequired
matches ^[0-9a-f]{64}$
slabsobject[]

Legacy compatibility field. Exact-slab redemption is deferred from the current integration scope; use supported raw-card and sealed-item lines or pack selection.

min items 1 · max items 20
Show properties
Array of object
graderstringrequired
Allowed:psabgscgc
certstringrequired

Legacy graded-card certificate identifier retained for compatibility. Graded-card deposits, cert lookups and exact-slab workflows are deferred from the current integration scope.

max length 40
unitRefstring
matches ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:0$
storeLinkIdstring
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
storeRefstring
min length 1 · max length 64
submissionKeystringrequired
min length 8 · max length 128 · matches ^[A-Za-z0-9_.:-]+$
visibleOrderNumberstring
min length 1 · max length 100
Responses
200

Success

dataobjectrequired
Show properties
effectsstring[]required
operationIdstringrequired
outcomestringrequired
adapterobjectrequired
Show properties
idstringrequired
min length 1
labelstringrequired
min length 1
providerVerifiedbooleanrequired
cancellationobject
Show properties
deadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
eligiblebooleanrequired
orderobjectrequired
Show properties
customerLabelstring | nullrequired
idstringrequired
kindstringrequired
Allowed:ordinaryredemptionreshipship_back
receiptobjectrequired
Show properties
operationIdstring | nullrequired
recordedAtstringrequired
visibleOrderNumberstring | nullrequired
cancellationobject | null
Show properties
Any of:
object
deadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
eligiblebooleanrequired
null
null
currentobject | nullrequired
Show properties
Any of:
object
insuranceobject | null
Show properties
Any of:
object
insuredbooleanrequired

Whether the order asks the warehouse to insure its one parcel. False is the explicit no-additional-insurance choice.

insuredValueobject | nullrequired

Declared value to insure, independent of goods and customs values. Null when not insured.

Show properties
Any of:
object
amountstringrequired
currencystringrequired
null
null
labelobject | nullrequired

Null until the warehouse buys the one label for this order, or when the order has more than one active shipment.

Show properties
Any of:
object
insuredboolean | nullrequired

Whether the warehouse's label reports additional coverage. Null when the label does not report it.

insuredValueobject | nullrequired
Show properties
Any of:
object
amountstringrequired
currencystringrequired
null
null
providerstring | nullrequired
Show properties
Any of:
string
string
null
null
null
null
providerstring | nullrequired

Coverage provider. carrier is the carrier's declared-value coverage.

Show properties
Any of:
string
string
null
null
null
null
requestedDeliveryConfirmationstring | null
Show properties
Any of:
string
string
null
null
orderDatestring | nullrequired
providerOrderNumberstring | nullrequired
recipientNamestring | nullrequired
statusstringrequired
Allowed:on_holdreadyshippedcanceledunknown
trackingobject[]required
Show properties
Array of object
deliveryConfirmationstring | null
Show properties
Any of:
string
string
null
null
carrierstring | nullrequired
numberstringrequired
shipDatestring | nullrequired
parcelEvidenceobject
Show properties
allParcelsCollectedboolean | nullrequired
coveragestringrequired
Allowed:completeincomplete
membershipObservedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
statestringrequired
Allowed:confirmedpendingincompletestaleunavailableunknown
parcelsobject[]required
Show properties
Array of object
idstringrequired
carrierstring | nullrequired
numberstringrequired
statestringrequired
Allowed:confirmedpendingunavailableunknown
eventobject | nullrequired
Show properties
Any of:
object
detailCodestringrequired
occurredAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
reportedAtstring | nullrequired
null
null
detailCodestring | nullrequired
observedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
establishedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
refreshstringrequired
Allowed:currentunavailableunknownstale
simulatedbooleanrequired
customerNotesstring | nullrequired
holdUntilDatestring | nullrequired
itemsobject[]required
Show properties
Array of object
declaredUnitValuestring | null
namestring | nullrequired
productIdstring | null
quantityinteger | nullrequired
Show properties
Any of:
integer
integer
null
null
skustring | nullrequired
unitPricestring | null
recipientobject | nullrequired
Show properties
Any of:
object
citystring | nullrequired
companystring | nullrequired
countrystring | nullrequired
emailstring | nullrequired
namestring | nullrequired
phonestring | nullrequired
postalCodestring | nullrequired
statestring | nullrequired
street1string | nullrequired
street2string | nullrequired
null
null
revisionstringrequired
requestedShippingServicestring | nullrequired
null
null
packingExceptionobject | null

Redemption cards held while packing, each with its offer, response deadline and outcome. Null when no card was held.

Show properties
Any of:
object
estimateobject | nullrequired
Show properties
Any of:
object
amountstring | nullrequired

Estimated total in currency units. Null when a component is not yet known; unknown is never reported as zero.

asOfstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
basisstringrequired
completebooleanrequired

True only when every affected unit is applied and the amount is known. False while any unit is not applied, because that card is priced as ordered, and when the amount is null.

componentsobject[]required
Show properties
Array of object
amountstring | nullrequired
codestringrequired
currencystringrequired
min length 3 · max length 3
revisionintegerrequired
min 1 · max 9007199254740991
null
null
idstringrequired
recordedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
resolvedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
revisionintegerrequired
min 1 · max 9007199254740991
statusstringrequired

held keeps the order from shipping until every unit settles.

Allowed:heldresolved
unitsobject[]required
Show properties
Array of object
decisionobject | nullrequired
Show properties
Any of:
object
answerstringrequired
Allowed:accept_offerremove_card
decidedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
offerRevisionintegerrequired
min 1 · max 9007199254740991
operationIdstring | nullrequired

Operation ID of the answer that made this decision. Retry or recover an answer by this ID. Null when the warehouse or the deadline decided.

sourcestringrequired

answer is the customer's own answer; warehouse is a decision the warehouse recorded on the customer's instruction; deadline_default removes the card when the response window closes without one.

Allowed:answerwarehousedeadline_default
null
null
foundConditionstring | nullrequired
Show properties
Any of:
string
string
null
null
idstringrequired
lineIndexintegerrequired
min 0 · max 9007199254740991
offerobjectrequired
Show properties
conditionstring | nullrequired

Condition of the offered replacement card, when graded.

Show properties
Any of:
string
string
null
null
idstringrequired
kindstringrequired

replacement offers one reserved card; no_offer means the only choice is removing the card.

Allowed:replacementno_offer
productstring | nullrequired

The SKU of the offered replacement card, or null for no_offer.

readableAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
responseDeadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
revisionintegerrequired
min 1 · max 9007199254740991
orderedobjectrequired
Show properties
conditionstring | nullrequired
Show properties
Any of:
string
string
null
null
productstringrequired
skustring | nullrequired
outcomestringrequired
Allowed:awaiting_answerreceivedpendingappliedrefused
packCardOrdinalinteger | nullrequired
Show properties
Any of:
integer
integer
null
null
reasonstringrequired
Allowed:condition_mismatchmissingdamaged
responseDeadlineAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
unitIndexintegerrequired
min 0 · max 9007199254740991
null
null
sourceOrderIdstring | nullrequired
redemptionReferencestringrequired
min length 1 · max length 200
slabsobject[]

Historical exact-slab metadata retained for compatibility. Exact-slab workflows are deferred from the current integration scope.

Show properties
Array of object
certstringrequired
graderstringrequired
Allowed:psabgscgc
unitRefstringrequired
correlationIdstringrequired
min length 1 · max length 200
yugaCorrelationIdstringdeprecated

Deprecated alias of correlationId.

min length 1 · max length 200
metaobjectrequired
Show properties
requestIdstringrequired
default

Error

errorobjectrequired
Show properties
codestringrequired
Allowed:forbiddeninternal_errornot_foundprovider_data_invalidprovider_outcome_unknownprovider_unavailablerate_limitedstate_conflictunauthenticatedvalidation_errorwarehouse_not_ready
fieldsobject[]
Show properties
Array of object
codestringrequired
messagestringrequired
pathstringrequired
messagestringrequired
operationIdstring
metaobjectrequired
Show properties
requestIdstringrequired
Request
curl -X POST '/v1/organizations/org_example/orders/redemptions' \
  -H 'Authorization: Basic YOUR_CREDENTIALS' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "customerLabel": "Warehouse demo",
  "lines": [
    {
      "condition": "nm",
      "declaredUnitValue": {
        "amount": "12.50"
      },
      "productId": "product_ready_demo",
      "quantity": 1,
      "sku": "READY-DEMO-SKU"
    }
  ],
  "orderKey": "ready-redemption-demo-1",
  "orderNumber": "RED-DEMO-1",
  "recipient": {
    "city": "Toronto",
    "country": "CA",
    "name": "Taylor Example",
    "postalCode": "M5V 1E3",
    "state": "ON",
    "street1": "1 Example Street"
  },
  "redemptionReference": "ready-redemption-demo-1",
  "submissionKey": "ready-redemption-demo-1"
}'
Response
{
  "data": {
    "effects": [
      "order_associated",
      "order_created",
      "order_on_hold",
      "redemption_correlated",
      "redemption_stock_committed"
    ],
    "operationId": "operation_ready_redemption_demo",
    "outcome": "confirmed",
    "adapter": {
      "id": "partner-test-redemption",
      "label": "Partner TEST redemption adapter (isolated, not provider-verified)",
      "providerVerified": false
    },
    "cancellation": {
      "deadlineAt": "2026-10-02T01:00:00.000Z",
      "eligible": true
    },
    "order": {
      "customerLabel": "Warehouse demo",
      "id": "order_ready_redemption_demo",
      "kind": "redemption",
      "receipt": {
        "operationId": "operation_ready_redemption_demo",
        "recordedAt": "2026-10-02T00:00:00.000Z"
      },
      "visibleOrderNumber": "RED-DEMO-1",
      "current": {
        "orderDate": "2026-10-02",
        "providerOrderNumber": "demo-provider-order",
        "recipientName": "Taylor Example",
        "status": "on_hold",
        "tracking": [],
        "customerNotes": null,
        "holdUntilDate": null,
        "items": [
          {
            "declaredUnitValue": "12.5",
            "name": "Ready demo product",
            "quantity": 1,
            "sku": "READY-DEMO-SKU"
          }
        ],
        "recipient": {
          "city": "Toronto",
          "company": null,
          "country": "CA",
          "email": null,
          "name": "Taylor Example",
          "phone": null,
          "postalCode": "M5V 1E3",
          "state": "ON",
          "street1": "1 Example Street",
          "street2": null
        },
        "revision": "demo-revision-1",
        "requestedShippingService": null
      },
      "sourceOrderId": null
    },
    "redemptionReference": "ready-redemption-demo-1",
    "correlationId": "partner-test-ready-redemption-demo-1"
  },
  "meta": {
    "requestId": "example-createRedemptionOrder"
  }
}