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.
/v1/organizations/{orgId}/orders/redemptionsAuthorizationBasic auth · headerrequiredRegistered confidential integration credentials. Keep the secret server-side.
CookieAPI key · headerrequiredConsole-managed Vault session cookie; secure cookie naming may vary by environment.
AuthorizationBearer token (Vault TEST service token) · headerrequiredCustomer- 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.
AuthorizationBearer token (Vault organization API key) · headerrequiredOrganization-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.
orgIdstringrequiredapplication/jsondeliveryConfirmationstringnonedeliverysignatureadult_signaturedirect_signaturecustomerLabelstring | nullShow propertiesHide properties
stringnullfulfillmentSourceobjectShow propertiesHide properties
configurationRevisionstringrequiredsourceSignaturestringrequiredphysicalOriginEquivalenceRefstringrequiredv1WarehouseIdintegerrequiredmodestringrequiredconfigurationRevisionstringrequiredsourceSignaturestringrequiredphysicalOriginEquivalenceRefstringrequiredlinesobject[]Show propertiesHide properties
objectconditionstring | nullrequiredShow propertiesHide properties
stringnulldeclaredUnitValueobjectShow propertiesHide properties
amountstringrequiredproductIdstringrequiredquantityintegerrequiredskustringorderKeystringrequiredorderNumberstringpackobjectShow propertiesHide properties
cardOrdinalsinteger[]declaredUnitValuesobject[]Show propertiesHide properties
objectamountstringrequiredproductIdstringrequireddeploymentRefstringrequiredpackReferencestringrequiredsourceContentRevisionintegerrequiredsourceDigeststringrequiredrecipientobjectrequiredShow propertiesHide properties
addressLine1string | nullShow propertiesHide properties
stringnulladdressLine2string | nullShow propertiesHide properties
stringnulladdressLine3string | nullShow propertiesHide properties
stringnullcitystring | nullShow propertiesHide properties
stringnullcompanystring | nullShow propertiesHide properties
stringnullcompanyNamestring | nullShow propertiesHide properties
stringnullcontactNamestring | nullShow propertiesHide properties
stringnullcountrystring | nullShow propertiesHide properties
stringnullcountryCodestring | nullShow propertiesHide properties
stringnullemailstring | nullShow propertiesHide properties
stringnullnamestring | nullShow propertiesHide properties
stringnullphonestring | nullShow propertiesHide properties
stringnullpostalCodestring | nullShow propertiesHide properties
stringnullregionstring | nullShow propertiesHide properties
stringnullstatestring | nullShow propertiesHide properties
stringnullstreet1string | nullShow propertiesHide properties
stringnullstreet2string | nullShow propertiesHide properties
stringnullstreet3string | nullShow propertiesHide properties
stringnullredemptionReferencestringrequiredrequestedShippingServicestringrequestedShippingServiceReviewstringshippingQuoteobjectShow propertiesHide properties
deliveryConfirmationstringnonedeliverysignatureadult_signaturedirect_signatureinsuranceobjectShow propertiesHide properties
kindstringrequiredkindstringrequiredpackagesobject[]requiredShow propertiesHide properties
objectamountstringrequiredcurrencystringrequiredproviderstringrequiredcarrierparcelguardshipsurancexcoverreviewstringrequiredrequestedShippingServicestringrequiredrequestedShippingServiceReviewstringrequiredslabsobject[]Legacy compatibility field. Exact-slab redemption is deferred from the current integration scope; use supported raw-card and sealed-item lines or pack selection.
Show propertiesHide properties
objectgraderstringrequiredpsabgscgccertstringrequiredLegacy graded-card certificate identifier retained for compatibility. Graded-card deposits, cert lookups and exact-slab workflows are deferred from the current integration scope.
unitRefstringstoreLinkIdstringstoreRefstringsubmissionKeystringrequiredvisibleOrderNumberstringSuccess
dataobjectrequiredShow propertiesHide properties
effectsstring[]requiredoperationIdstringrequiredoutcomestringrequiredadapterobjectrequiredShow propertiesHide properties
idstringrequiredlabelstringrequiredproviderVerifiedbooleanrequiredcancellationobjectShow propertiesHide properties
deadlineAtstring<date-time>requiredeligiblebooleanrequiredorderobjectrequiredShow propertiesHide properties
customerLabelstring | nullrequiredidstringrequiredkindstringrequiredordinaryredemptionreshipship_backreceiptobjectrequiredShow propertiesHide properties
operationIdstring | nullrequiredrecordedAtstringrequiredvisibleOrderNumberstring | nullrequiredcancellationobject | nullShow propertiesHide properties
deadlineAtstring<date-time>requiredeligiblebooleanrequirednullcurrentobject | nullrequiredShow propertiesHide properties
insuranceobject | nullShow propertiesHide properties
insuredbooleanrequiredWhether the order asks the warehouse to insure its one parcel. False is the explicit no-additional-insurance choice.
insuredValueobject | nullrequiredDeclared value to insure, independent of goods and customs values. Null when not insured.
Show propertiesHide properties
amountstringrequiredcurrencystringrequirednulllabelobject | nullrequiredNull until the warehouse buys the one label for this order, or when the order has more than one active shipment.
Show propertiesHide properties
insuredboolean | nullrequiredWhether the warehouse's label reports additional coverage. Null when the label does not report it.
insuredValueobject | nullrequiredShow propertiesHide properties
amountstringrequiredcurrencystringrequirednullproviderstring | nullrequiredShow propertiesHide properties
stringnullnullproviderstring | nullrequiredCoverage provider. carrier is the carrier's declared-value coverage.
Show propertiesHide properties
stringnullnullrequestedDeliveryConfirmationstring | nullShow propertiesHide properties
stringnullorderDatestring | nullrequiredproviderOrderNumberstring | nullrequiredrecipientNamestring | nullrequiredstatusstringrequiredon_holdreadyshippedcanceledunknowntrackingobject[]requiredShow propertiesHide properties
objectdeliveryConfirmationstring | nullShow propertiesHide properties
stringnullcarrierstring | nullrequirednumberstringrequiredshipDatestring | nullrequiredparcelEvidenceobjectShow propertiesHide properties
allParcelsCollectedboolean | nullrequiredcoveragestringrequiredcompleteincompletemembershipObservedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullstatestringrequiredconfirmedpendingincompletestaleunavailableunknownparcelsobject[]requiredShow propertiesHide properties
objectidstringrequiredcarrierstring | nullrequirednumberstringrequiredstatestringrequiredconfirmedpendingunavailableunknowneventobject | nullrequiredShow propertiesHide properties
detailCodestringrequiredoccurredAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullreportedAtstring | nullrequirednulldetailCodestring | nullrequiredobservedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullestablishedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullrefreshstringrequiredcurrentunavailableunknownstalesimulatedbooleanrequiredcustomerNotesstring | nullrequiredholdUntilDatestring | nullrequireditemsobject[]requiredShow propertiesHide properties
objectdeclaredUnitValuestring | nullnamestring | nullrequiredproductIdstring | nullquantityinteger | nullrequiredShow propertiesHide properties
integernullskustring | nullrequiredunitPricestring | nullrecipientobject | nullrequiredShow propertiesHide properties
citystring | nullrequiredcompanystring | nullrequiredcountrystring | nullrequiredemailstring | nullrequirednamestring | nullrequiredphonestring | nullrequiredpostalCodestring | nullrequiredstatestring | nullrequiredstreet1string | nullrequiredstreet2string | nullrequirednullrevisionstringrequiredrequestedShippingServicestring | nullrequirednullpackingExceptionobject | nullRedemption cards held while packing, each with its offer, response deadline and outcome. Null when no card was held.
Show propertiesHide properties
estimateobject | nullrequiredShow propertiesHide properties
amountstring | nullrequiredEstimated total in currency units. Null when a component is not yet known; unknown is never reported as zero.
asOfstring<date-time>requiredbasisstringrequiredcompletebooleanrequiredTrue 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[]requiredShow propertiesHide properties
objectamountstring | nullrequiredcodestringrequiredcurrencystringrequiredrevisionintegerrequirednullidstringrequiredrecordedAtstring<date-time>requiredresolvedAtstring<date-time> | nullrequiredShow propertiesHide properties
string<date-time>nullrevisionintegerrequiredstatusstringrequiredheld keeps the order from shipping until every unit settles.
heldresolvedunitsobject[]requiredShow propertiesHide properties
objectdecisionobject | nullrequiredShow propertiesHide properties
answerstringrequiredaccept_offerremove_carddecidedAtstring<date-time>requiredofferRevisionintegerrequiredoperationIdstring | nullrequiredOperation ID of the answer that made this decision. Retry or recover an answer by this ID. Null when the warehouse or the deadline decided.
sourcestringrequiredanswer 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.
answerwarehousedeadline_defaultnullfoundConditionstring | nullrequiredShow propertiesHide properties
stringnullidstringrequiredlineIndexintegerrequiredofferobjectrequiredShow propertiesHide properties
conditionstring | nullrequiredCondition of the offered replacement card, when graded.
Show propertiesHide properties
stringnullidstringrequiredkindstringrequiredreplacement offers one reserved card; no_offer means the only choice is removing the card.
replacementno_offerproductstring | nullrequiredThe SKU of the offered replacement card, or null for no_offer.
readableAtstring<date-time>requiredresponseDeadlineAtstring<date-time>requiredrevisionintegerrequiredorderedobjectrequiredShow propertiesHide properties
conditionstring | nullrequiredShow propertiesHide properties
stringnullproductstringrequiredskustring | nullrequiredoutcomestringrequiredawaiting_answerreceivedpendingappliedrefusedpackCardOrdinalinteger | nullrequiredShow propertiesHide properties
integernullreasonstringrequiredcondition_mismatchmissingdamagedresponseDeadlineAtstring<date-time>requiredunitIndexintegerrequirednullsourceOrderIdstring | nullrequiredredemptionReferencestringrequiredslabsobject[]Historical exact-slab metadata retained for compatibility. Exact-slab workflows are deferred from the current integration scope.
Show propertiesHide properties
objectcertstringrequiredgraderstringrequiredpsabgscgcunitRefstringrequiredcorrelationIdstringrequiredyugaCorrelationIdstringdeprecatedDeprecated alias of correlationId.
metaobjectrequiredShow propertiesHide properties
requestIdstringrequiredError
errorobjectrequiredShow propertiesHide properties
codestringrequiredforbiddeninternal_errornot_foundprovider_data_invalidprovider_outcome_unknownprovider_unavailablerate_limitedstate_conflictunauthenticatedvalidation_errorwarehouse_not_readyfieldsobject[]Show propertiesHide properties
objectcodestringrequiredmessagestringrequiredpathstringrequiredmessagestringrequiredoperationIdstringmetaobjectrequiredShow propertiesHide properties
requestIdstringrequired