PlaceOrder buys one or more products, settled from the reseller’s prepaid
wallet. It is asynchronous: the order is accepted and fulfilled in the
background, so the response carries the order id and a status to poll. The
request MUST carry an Idempotency-Key header, so a retried request never
places a second order.
A unique key so a retried request never places a second order. Reuse the same key to retry a call safely; reusing it with a different body is a conflict.
reference is an optional identifier you attach to the order to correlate it
with your own system and look it up later. Reusing an Idempotency-Key with a
different reference is a conflict.
Money is an amount in a currency's minor units, together with the currency's
ISO-4217 code and its number of decimal places, so the amount can be
interpreted without assuming the currency. XOF (the West-African CFA franc) has
no minor unit, so an XOF amount is a whole franc value.
order is the accepted order. It is settled from the wallet at placement, so it
is born already paid: its status is "processing" while it is being fulfilled,
or "completed" when fulfillment is immediate. It is never "pending" -- the
developer API charges synchronously, so an order awaiting payment is not a
state it produces. Poll the order to follow it to "completed".
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"SODACARDS","description":"The SODACARDS developer API: sell gift cards and game top-ups from your own systems.","colors":{"primary":"#003087","light":"#307FE2","dark":"#00205B"},"favicon":"https://mintcdn.com/sodacards/ddPq6lebxk4NI_Jz/favicon.svg?fit=max\u0026auto=format\u0026n=ddPq6lebxk4NI_Jz\u0026q=85\u0026s=ccdd7deeac109e2c08a80b3a8bb9421a","navbar":{"primary":{"type":"button","label":"Dashboard","href":"https://developer.sodacards.com"}},"footer":{"socials":{"website":"https://sodacards.com"}},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"sodacards","hasAudioNarration":false,"actualSubdomain":"sodacards","customDomains":["developer.sodacards.com"],"gitSource":{"type":"github","owner":"sodacards","repo":"sodacards-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6aa30e18f59aad5d55c10359","collectionId":"79bf27d2-dc64-42f0-aa5b-b5eb5c438857","liveDeploymentHistoryId":"6aa30e18f59aad5d55c10359","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6aa30e18f59aad5d55c10359","clientVersion":"0.0.4054","searchFilterCounts":[{"language":"default","tag":"API Reference","count":34},{"language":"default","tag":"Guides","count":13},{"language":"default","tag":"Endpoints","count":12},{"language":"default","tag":"Core concepts","count":6},{"language":"default","tag":"Webhook events","count":5},{"language":"default","tag":"Get started","count":4},{"language":"default","tag":"Webhooks","count":2},{"language":"default","tag":"Reference","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true,"deflection":{"enabled":true,"email":"contact@sodacards.com"}},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"privacy":{"consentBanner":{"enabled":false}},"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/place-an-order","slug":"/api-reference/place-an-order","pageMetadata":{"title":"Place an order","description":"PlaceOrder buys one or more products, settled from the reseller's prepaid\n wallet. It is asynchronous: the order is accepted and fulfilled in the\n background, so the response carries the order id and a status to poll. The\n request MUST carry an Idempotency-Key header, so a retried request never\n places a second order.","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml post /v1/orders","href":"/api-reference/place-an-order","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"PlaceOrder buys one or more products, settled from the reseller’s prepaid\\nwallet. It is asynchronous: the order is accepted and fulfilled in the\\nbackground, so the response carries the order id and a status to poll. The\\nrequest MUST carry an Idempotency-Key header, so a retried request never\\nplaces a second order.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Place an order","description":"PlaceOrder buys one or more products, settled from the reseller's prepaid\n wallet. It is asynchronous: the order is accepted and fulfilled in the\n background, so the response carries the order id and a status to poll. The\n request MUST carry an Idempotency-Key header, so a retried request never\n places a second order.","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml post /v1/orders","href":"/api-reference/place-an-order","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Place an order","description":"PlaceOrder buys one or more products, settled from the reseller's prepaid\n wallet. It is asynchronous: the order is accepted and fulfilled in the\n background, so the response carries the order id and a status to poll. The\n request MUST carry an Idempotency-Key header, so a retried request never\n places a second order.","operationId":"placeOrder","parameters":["c1384a99-21ac-491e-ad74-75f010fbc1c4"],"requestBody":"ac627fe3-63f7-4b60-9a58-8ffa6a7b0eaa","responses":{"200":"8583a050-de05-4c57-a18f-076665fb56df","default":"15ba2417-5a8e-455a-af0d-3f8237ec45a9"},"x-codeSamples":[{"lang":"python","label":"Python","source":"import os, sodacards\nfrom sodacards.models import (\n SodacardsDevpublicV1PlaceOrderRequest,\n SodacardsDevpublicV1OrderLine,\n)\n\nconfig = sodacards.Configuration(host=\"https://api.sodacards.com\")\nconfig.api_key[\"ApiKeyAuth\"] = os.environ[\"SODACARDS_API_KEY\"]\nclient = sodacards.DefaultApi(sodacards.ApiClient(config))\n\norder = client.place_order(\n SodacardsDevpublicV1PlaceOrderRequest(\n lines=[SodacardsDevpublicV1OrderLine(product_id=\"prod_123\", quantity=1)],\n reference=\"order-0001\",\n ),\n idempotency_key=\"order-0001\",\n)\n"},{"lang":"typescript","label":"TypeScript","source":"import { Sodacards } from \"@sodacards/sdk\";\n\nconst sodacards = new Sodacards({ apiKeyAuth: process.env.SODACARDS_API_KEY });\n\nconst order = await sodacards.placeOrder({\n idempotencyKey: \"order-0001\",\n body: {\n lines: [{ productId: \"prod_123\", quantity: 1 }],\n reference: \"order-0001\",\n },\n});\n"},{"lang":"go","label":"Go","source":"client := sodacards.NewAPIClient(sodacards.NewConfiguration())\nauth := context.WithValue(context.Background(), sodacards.ContextAPIKeys,\n map[string]sodacards.APIKey{\"ApiKeyAuth\": {Key: os.Getenv(\"SODACARDS_API_KEY\")}})\n\nline := sodacards.NewSodacardsDevpublicV1OrderLine()\nline.SetProductId(\"prod_123\")\nline.SetQuantity(1)\n\nbody := sodacards.NewSodacardsDevpublicV1PlaceOrderRequest()\nbody.SetLines([]sodacards.SodacardsDevpublicV1OrderLine{*line})\nbody.SetReference(\"order-0001\")\n\norder, _, err := client.DefaultAPI.PlaceOrder(auth).\n IdempotencyKey(\"order-0001\").\n SodacardsDevpublicV1PlaceOrderRequest(*body).\n Execute()\n"},{"lang":"php","label":"PHP","source":"$config = Sodacards\\Configuration::getDefaultConfiguration()\n ->setApiKey('X-API-Key', getenv('SODACARDS_API_KEY'));\n$client = new Sodacards\\Api\\DefaultApi(new GuzzleHttp\\Client(), $config);\n\n$order = $client->placeOrder('order-0001', new Sodacards\\Model\\SodacardsDevpublicV1PlaceOrderRequest([\n 'lines' => [\n new Sodacards\\Model\\SodacardsDevpublicV1OrderLine([\n 'product_id' => 'prod_123',\n 'quantity' => 1,\n ]),\n ],\n 'reference' => 'order-0001',\n]));\n"}],"method":"post","type":"path","servers":["13071a22-6e13-4590-9518-31f4d94d91a4"],"security":["b8dca23a-7fb6-4dab-9348-45f5fbe13399"],"path":"/v1/orders","baseUrlOptions":["https://api.sodacards.com"],"title":"Place an order","codeSamples":[{"label":"Python","lang":"python","source":"import os, sodacards\nfrom sodacards.models import (\n SodacardsDevpublicV1PlaceOrderRequest,\n SodacardsDevpublicV1OrderLine,\n)\n\nconfig = sodacards.Configuration(host=\"https://api.sodacards.com\")\nconfig.api_key[\"ApiKeyAuth\"] = os.environ[\"SODACARDS_API_KEY\"]\nclient = sodacards.DefaultApi(sodacards.ApiClient(config))\n\norder = client.place_order(\n SodacardsDevpublicV1PlaceOrderRequest(\n lines=[SodacardsDevpublicV1OrderLine(product_id=\"prod_123\", quantity=1)],\n reference=\"order-0001\",\n ),\n idempotency_key=\"order-0001\",\n)\n"},{"label":"TypeScript","lang":"typescript","source":"import { Sodacards } from \"@sodacards/sdk\";\n\nconst sodacards = new Sodacards({ apiKeyAuth: process.env.SODACARDS_API_KEY });\n\nconst order = await sodacards.placeOrder({\n idempotencyKey: \"order-0001\",\n body: {\n lines: [{ productId: \"prod_123\", quantity: 1 }],\n reference: \"order-0001\",\n },\n});\n"},{"label":"Go","lang":"go","source":"client := sodacards.NewAPIClient(sodacards.NewConfiguration())\nauth := context.WithValue(context.Background(), sodacards.ContextAPIKeys,\n map[string]sodacards.APIKey{\"ApiKeyAuth\": {Key: os.Getenv(\"SODACARDS_API_KEY\")}})\n\nline := sodacards.NewSodacardsDevpublicV1OrderLine()\nline.SetProductId(\"prod_123\")\nline.SetQuantity(1)\n\nbody := sodacards.NewSodacardsDevpublicV1PlaceOrderRequest()\nbody.SetLines([]sodacards.SodacardsDevpublicV1OrderLine{*line})\nbody.SetReference(\"order-0001\")\n\norder, _, err := client.DefaultAPI.PlaceOrder(auth).\n IdempotencyKey(\"order-0001\").\n SodacardsDevpublicV1PlaceOrderRequest(*body).\n Execute()\n"},{"label":"PHP","lang":"php","source":"$config = Sodacards\\Configuration::getDefaultConfiguration()\n ->setApiKey('X-API-Key', getenv('SODACARDS_API_KEY'));\n$client = new Sodacards\\Api\\DefaultApi(new GuzzleHttp\\Client(), $config);\n\n$order = $client->placeOrder('order-0001', new Sodacards\\Model\\SodacardsDevpublicV1PlaceOrderRequest([\n 'lines' => [\n new Sodacards\\Model\\SodacardsDevpublicV1OrderLine([\n 'product_id' => 'prod_123',\n 'quantity' => 1,\n ]),\n ],\n 'reference' => 'order-0001',\n]));\n"}],"requiredOnlyExamples":false,"requestExampleType":"codeSamples","responseExampleType":"generated"},"dependencies":{"parameters":{"c1384a99-21ac-491e-ad74-75f010fbc1c4":{"name":"Idempotency-Key","in":"header","description":"A unique key so a retried request never places a second order. Reuse the same key to retry a call safely; reusing it with a different body is a conflict.","required":true,"explode":false,"schema":{"type":"string","isRequired":true,"description":"A unique key so a retried request never places a second order. Reuse the same key to retry a call safely; reusing it with a different body is a conflict.","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","title":"product_id","description":"product_id is the id of the product to buy (a catalog product id).","uniqueKey":"lines.items.[INDEX].productId","typeLabel":"string"},"quantity":{"type":"integer","title":"quantity","format":"int32","description":"quantity is how many units to buy on this line (at least one).","uniqueKey":"lines.items.[INDEX].quantity","typeLabel":"integer\u003cint32>"},"inputFields":{"type":"object","title":"input_fields","additionalProperties":{"type":"string","title":"value","uniqueKey":"lines.items.[INDEX].inputFields.additionalProperties","typeLabel":"string"},"description":"input_fields holds the required purchase-form values, keyed by field name.","uniqueKey":"lines.items.[INDEX].inputFields","typeLabel":"input_fields · object"}},"title":"OrderLine","additionalProperties":false,"description":"OrderLine is one product to buy on an order. input_fields carries the\n purchase-form values a product requires (for example a game player id), keyed\n by the field name from the product definition.","uniqueKey":"lines.items.[INDEX]","typeLabel":"OrderLine · object"},"title":"lines","description":"lines are the products to buy and how many of each. At least one is required.","uniqueKey":"lines","typeLabel":"OrderLine · object[]"},"reference":{"type":"string","title":"reference","description":"reference is an optional identifier you attach to the order to correlate it\n with your own system and look it up later. Reusing an Idempotency-Key with a\n different reference is a conflict.","uniqueKey":"reference","typeLabel":"string"},"maxTotal":{"oneOf":[{"type":"object","title":"Money","description":"Money is an amount in a currency's minor units, together with the currency's\n ISO-4217 code and its number of decimal places, so the amount can be\n interpreted without assuming the currency. XOF (the West-African CFA franc) has\n no minor unit, so an XOF amount is a whole franc value.","properties":{"amount":{"oneOf":[{"type":"integer","examples":["5000"],"title":"amount","format":"int64","description":"amount is the value in the currency's minor units. It is a 64-bit integer, so\n JSON carries it as a string (protobuf's mapping for int64, which avoids losing\n precision in languages whose numbers are 53-bit): read it as an integer.","uniqueKey":"maxTotal.oneOf.0.amount.oneOf.0","typeLabel":"integer\u003cint64>"},{"type":"string","examples":["5000"],"title":"amount","format":"int64","description":"amount is the value in the currency's minor units. It is a 64-bit integer, so\n JSON carries it as a string (protobuf's mapping for int64, which avoids losing\n precision in languages whose numbers are 53-bit): read it as an integer.","uniqueKey":"maxTotal.oneOf.0.amount.oneOf.1","typeLabel":"string\u003cint64>"}],"uniqueKey":"maxTotal.oneOf.0.amount","typeLabel":"integer\u003cint64> | string\u003cint64>"},"currency":{"type":"string","examples":["XOF"],"title":"currency","description":"currency is the ISO-4217 code, e.g. \"XOF\".","uniqueKey":"maxTotal.oneOf.0.currency","typeLabel":"string"},"minorUnitExponent":{"type":"integer","examples":["0"],"title":"minor_unit_exponent","format":"int32","description":"minor_unit_exponent is the currency's number of decimal places (0 for XOF,\n 2 for USD): amount divided by 10^minor_unit_exponent is the major-unit value.\n The example is 0 on purpose: XOF has no minor unit, and an explicit example\n keeps the field visible in the docs even though its value is a zero.","uniqueKey":"maxTotal.oneOf.0.minorUnitExponent","typeLabel":"integer\u003cint32>"}},"additionalProperties":false,"uniqueKey":"maxTotal.oneOf.0","typeLabel":"Money · object"},{"type":"null","title":"max_total","description":"max_total is an OPTIONAL ceiling on what you accept to be charged for this\n order. If the order's real total is above it, the order is rejected BEFORE any\n wallet debit (error price_exceeds_maximum), so a price change between reading\n the catalog and placing the order can never silently overcharge you. Omit it to\n accept whatever the price is at order time (the previous, unguarded behavior).\n It must be in the functional currency (XOF) with minor_unit_exponent 0; a\n different currency is rejected. The refusal carries the current total, which is\n informative AT THAT INSTANT -- not a reservation: the price may move again\n before you retry. A rejected order creates nothing and does not consume the\n Idempotency-Key, so you may retry the same key with a higher max_total.","uniqueKey":"maxTotal.oneOf.1","typeLabel":"null"}],"uniqueKey":"maxTotal","typeLabel":"Money · object | null"}},"title":"PlaceOrderRequest","additionalProperties":false,"uniqueKey":"","typeLabel":"PlaceOrderRequest · object"},"examples":{"Example":{"title":"Example","value":{"lines":[{"productId":"\u003cstring>","quantity":123,"inputFields":{}}],"reference":"\u003cstring>","maxTotal":{"amount":"5000","currency":"XOF","minorUnitExponent":"0"}}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"8583a050-de05-4c57-a18f-076665fb56df":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","title":"id","description":"id identifies the order; use it to poll the order and reveal its codes.","uniqueKey":"order.id","typeLabel":"string"},"status":{"type":"string","title":"status","enum":["pending","processing","completed","failed","refunded"],"description":"status is the order's current state: \"pending\", \"processing\", \"completed\",\n \"failed\" or \"refunded\".","uniqueKey":"order.status","typeLabel":"enum\u003cstring>"},"total":{"type":"object","properties":{"amount":{"oneOf":[{"type":"integer","examples":["5000"],"title":"amount","format":"int64","description":"amount is the value in the currency's minor units. It is a 64-bit integer, so\n JSON carries it as a string (protobuf's mapping for int64, which avoids losing\n precision in languages whose numbers are 53-bit): read it as an integer.","uniqueKey":"order.total.amount.oneOf.0","typeLabel":"integer\u003cint64>"},{"type":"string","examples":["5000"],"title":"amount","format":"int64","description":"amount is the value in the currency's minor units. It is a 64-bit integer, so\n JSON carries it as a string (protobuf's mapping for int64, which avoids losing\n precision in languages whose numbers are 53-bit): read it as an integer.","uniqueKey":"order.total.amount.oneOf.1","typeLabel":"string\u003cint64>"}],"uniqueKey":"order.total.amount","typeLabel":"integer\u003cint64> | string\u003cint64>"},"currency":{"type":"string","examples":["XOF"],"title":"currency","description":"currency is the ISO-4217 code, e.g. \"XOF\".","uniqueKey":"order.total.currency","typeLabel":"string"},"minorUnitExponent":{"type":"integer","examples":["0"],"title":"minor_unit_exponent","format":"int32","description":"minor_unit_exponent is the currency's number of decimal places (0 for XOF,\n 2 for USD): amount divided by 10^minor_unit_exponent is the major-unit value.\n The example is 0 on purpose: XOF has no minor unit, and an explicit example\n keeps the field visible in the docs even though its value is a zero.","uniqueKey":"order.total.minorUnitExponent","typeLabel":"integer\u003cint32>"}},"title":"total","additionalProperties":false,"description":"total is the amount charged to the reseller's wallet, in the currency of Money.","uniqueKey":"order.total","typeLabel":"total · object"}},"title":"order","additionalProperties":false,"description":"order is the accepted order. It is settled from the wallet at placement, so it\n is born already paid: its status is \"processing\" while it is being fulfilled,\n or \"completed\" when fulfillment is immediate. It is never \"pending\" -- the\n developer API charges synchronously, so an order awaiting payment is not a\n state it produces. Poll the order to follow it to \"completed\".","uniqueKey":"order","typeLabel":"order · object"}},"title":"PlaceOrderResponse","additionalProperties":false,"uniqueKey":"","typeLabel":"PlaceOrderResponse · object"},"examples":{"Example":{"title":"Example","value":{"order":{"id":"\u003cstring>","status":"pending","total":{"amount":"5000","currency":"XOF","minorUnitExponent":"0"}}}}},"exampleType":"generated"}},"exampleType":"generated"},"15ba2417-5a8e-455a-af0d-3f8237ec45a9":{"description":"Error. The body is an RFC 9457 problem+json object; switch on `code` for the machine-readable reason.","content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A stable URI identifying the error kind; it resolves to the docs section for that code.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","description":"A short, human-readable summary of the error kind.","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","format":"int32","description":"The HTTP status code, repeated in the body for convenience.","isRequired":true,"uniqueKey":"status","typeLabel":"integer\u003cint32>"},"code":{"type":"string","description":"The machine-readable reason (e.g. \"insufficient_balance\"): switch on this, never on the human text.","isRequired":true,"uniqueKey":"code","typeLabel":"string"},"detail":{"type":"string","description":"A human-readable explanation of this specific occurrence. May be absent.","uniqueKey":"detail","typeLabel":"string"},"request_id":{"type":"string","description":"Identifies this request in support conversations. May be absent.","uniqueKey":"request_id","typeLabel":"string"}},"required":["type","title","status","code"],"description":"An RFC 9457 problem+json error. Switch on `code`, the stable machine-readable reason; the HTTP status frames the broad category.","uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":123,"code":"\u003cstring>","detail":"\u003cstring>","request_id":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"b8dca23a-7fb6-4dab-9348-45f5fbe13399":{"ApiKeyAuth":{"type":"apiKey","description":"Your API key, prefixed sc_live_ or sc_test_.","name":"X-API-Key","in":"header","scopes":[]}}},"servers":{"13071a22-6e13-4590-9518-31f4d94d91a4":{"url":"https://api.sodacards.com"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","description":"Your API key, prefixed sc_live_ or sc_test_.","name":"X-API-Key","in":"header","scopes":[]},"schema":{"title":"X-API-Key","type":"string","description":"Your API key, prefixed sc_live_ or sc_test_.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"ApiKeyAuth","name":"X-API-Key"}],"title":"ApiKeyAuth"}]},"originalFileLocation":"api-reference/sodacards.yaml"},"subdomain":"sodacards","siteName":"SODACARDS","title":"Place an order - SODACARDS","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-10T20:08:08.364Z","originalFileLocation":"api-reference/place-an-order.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"PlaceOrder buys one or more products, settled from the reseller\u0026#x27;s prepaid wallet. It is asynchronous: the order is accepted and fulfilled in the background, so the response carries the order id and a status to poll. The request MUST carry an Idempotency-Key header, so a retried request never places a second order.\">\u003cmeta data-mint-head name=\"application-name\" content=\"SODACARDS\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Place an order - SODACARDS\">\u003cmeta data-mint-head property=\"og:description\" content=\"PlaceOrder buys one or more products, settled from the reseller\u0026#x27;s prepaid wallet. It is asynchronous: the order is accepted and fulfilled in the background, so the response carries the order id and a status to poll. The request MUST carry an Idempotency-Key header, so a retried request never places a second order.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"SODACARDS\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://developer.sodacards.com/api-reference/place-an-order\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://sodacards.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Place+an+order\u0026amp;description=PlaceOrder+buys+one+or+more+products%2C+settled+from+the+reseller%27s+prepaid%0A+wallet.+It+is+asynchronous%3A+the+order+is+accepted+and+fulfilled+in+the%0A+background%2C+s\u0026amp;theme=c9f1ca68f8a7ee5e1ae08f76\u0026amp;signature=f121df6ea4d72913e114789144009ace36fa8d23d3a06e4632e0bf3c8bfd5a9a\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Place an order - SODACARDS\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"PlaceOrder buys one or more products, settled from the reseller\u0026#x27;s prepaid wallet. It is asynchronous: the order is accepted and fulfilled in the background, so the response carries the order id and a status to poll. The request MUST carry an Idempotency-Key header, so a retried request never places a second order.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://sodacards.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Place+an+order\u0026amp;description=PlaceOrder+buys+one+or+more+products%2C+settled+from+the+reseller%27s+prepaid%0A+wallet.+It+is+asynchronous%3A+the+order+is+accepted+and+fulfilled+in+the%0A+background%2C+s\u0026amp;theme=c9f1ca68f8a7ee5e1ae08f76\u0026amp;signature=f121df6ea4d72913e114789144009ace36fa8d23d3a06e4632e0bf3c8bfd5a9a\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/sodacards/HLRyJX__TDaDu-j6/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"SODACARDS\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#003087\">\u003clink data-mint-head rel=\"canonical\" href=\"https://developer.sodacards.com/api-reference/place-an-order\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/place-an-order.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://developer.sodacards.com/#organization\",\"name\":\"SODACARDS\",\"url\":\"https://developer.sodacards.com\"},{\"@type\":\"WebSite\",\"@id\":\"https://developer.sodacards.com#website\",\"name\":\"SODACARDS\",\"url\":\"https://developer.sodacards.com\",\"publisher\":{\"@id\":\"https://developer.sodacards.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://developer.sodacards.com/api-reference/place-an-order#webpage\",\"url\":\"https://developer.sodacards.com/api-reference/place-an-order\",\"name\":\"Place an order\",\"description\":\"PlaceOrder buys one or more products, settled from the reseller's prepaid wallet. It is asynchronous: the order is accepted and fulfilled in the background, so the response carries the order id and a status to poll. The request MUST carry an Idempotency-Key header, so a retried request never places a second order.\",\"dateModified\":\"2026-09-10T20:08:08.364Z\",\"isPartOf\":{\"@id\":\"https://developer.sodacards.com#website\"},\"breadcrumb\":{\"@id\":\"https://developer.sodacards.com/api-reference/place-an-order#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://developer.sodacards.com/api-reference/place-an-order#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://developer.sodacards.com/api-reference/get-wallet-balance\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Reference\",\"item\":\"https://developer.sodacards.com/api-reference/get-wallet-balance\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Place an order\",\"item\":\"https://developer.sodacards.com/api-reference/place-an-order\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://developer.sodacards.com/api-reference/place-an-order#apireference\",\"headline\":\"Place an order\",\"name\":\"Place an order\",\"description\":\"PlaceOrder buys one or more products, settled from the reseller's prepaid wallet. It is asynchronous: the order is accepted and fulfilled in the background, so the response carries the order id and a status to poll. The request MUST carry an Idempotency-Key header, so a retried request never places a second order.\",\"url\":\"https://developer.sodacards.com/api-reference/place-an-order\",\"mainEntityOfPage\":{\"@id\":\"https://developer.sodacards.com/api-reference/place-an-order#webpage\"},\"dateModified\":\"2026-09-10T20:08:08.364Z\",\"publisher\":{\"@id\":\"https://developer.sodacards.com/#organization\"},\"isPartOf\":{\"@id\":\"https://developer.sodacards.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"SODACARDS\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"SODACARDS","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"Endpoints","pages":[{"group":"API Reference","pages":[{"title":"Get wallet balance","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/balance","href":"/api-reference/get-wallet-balance"},{"title":"List catalog products","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/catalog","href":"/api-reference/list-catalog-products"},{"title":"List orders","description":"ListOrders returns a page of the reseller's orders, newest first. It is\n cursor-paginated: pass next_cursor from the previous page to fetch the next.\n A live key lists live orders and a test key lists its own sandbox orders.","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/orders","href":"/api-reference/list-orders"},{"title":"Place an order","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml post /v1/orders","href":"/api-reference/place-an-order"},{"title":"Get an order","description":"GetOrder returns one of the reseller's orders by id, with its lines and\n current status. A live key reads live orders and a test key reads its own\n sandbox orders; an id that is not the caller's is reported as not found.","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/orders/{id}","href":"/api-reference/get-an-order"},{"title":"Reveal order codes","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/orders/{id}/codes","href":"/api-reference/reveal-order-codes"},{"title":"Ping","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/ping","href":"/api-reference/ping"},{"title":"Get a product","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/products/{id}","href":"/api-reference/get-a-product"},{"title":"List webhook endpoints","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml get /v1/webhooks","href":"/api-reference/list-webhook-endpoints"},{"title":"Register a webhook endpoint","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml post /v1/webhooks","href":"/api-reference/register-a-webhook-endpoint"},{"title":"Delete a webhook endpoint","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml delete /v1/webhooks/{id}","href":"/api-reference/delete-a-webhook-endpoint"},{"title":"Rotate a webhook signing secret","deprecated":null,"version":null,"openapi":"/api-reference/sodacards.yaml post /v1/webhooks/{id}/rotate","href":"/api-reference/rotate-a-webhook-signing-secret"}]}]},{"group":"Webhook events","pages":[{"group":"API Reference","pages":[{"title":"An order was fulfilled and its codes are ready to fetch","version":null,"deprecated":null,"openapi":"/api-reference/webhooks.yaml webhook order.fulfilled","href":"/api-reference/an-order-was-fulfilled-and-its-codes-are-ready-to-fetch"},{"title":"An order could not be auto fulfilled and is being handled","version":null,"deprecated":null,"openapi":"/api-reference/webhooks.yaml webhook order.needs_attention","href":"/api-reference/an-order-could-not-be-auto-fulfilled-and-is-being-handled"},{"title":"An order was refunded","version":null,"deprecated":null,"openapi":"/api-reference/webhooks.yaml webhook order.refunded","href":"/api-reference/an-order-was-refunded"},{"title":"Your prepaid wallet was credited","version":null,"deprecated":null,"openapi":"/api-reference/webhooks.yaml webhook wallet.credited","href":"/api-reference/your-prepaid-wallet-was-credited"},{"title":"Your prepaid wallet dropped below your alert threshold","version":null,"deprecated":null,"openapi":"/api-reference/webhooks.yaml webhook wallet.low_balance","href":"/api-reference/your-prepaid-wallet-dropped-below-your-alert-threshold"}]}]}]}]},"basePath":"","title":"Place an order - SODACARDS","buildId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","deploymentId":"dpl_345ReqzYaAjzS9QpeJemsKdb7KDj","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-C8RPHPxo.js","utils-0BK-9q6z.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-DfjzsUJT.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-B4v9psJ4.js","snippetPresets-CpTQv-Ez.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-BNP-Fvr0.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-BSgu6h1D.js","shallow-Biv1i9Gs.js","getApiPlaygroundDisplay-BoGOXhtF.js","CodeSnippet-DvQoT18_.js","CodeSnippets-Dnpa15xT.js","Page-Buji1S4J.js","getPastedJson-xAIyhUFE.js","icon-S6FBih11.js","MethodPill-SaYeUZyk.js","DuplicateIcon-Cs-p3v2Q.js","createIcon-DjCFEoHq.js","DynamicMarkdown-BcnBltEQ.js","SectionHeading-BUBl0eEF.js","axios-vUo_bRtp.js","Markdown-h4cOoD8d.js","clsx-B2v50t8t.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-DJnKvr0g.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-BHrrjR1K.js"]}