> For the complete documentation index, see [llms.txt](https://docs.2checkout.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.2checkout.com/api-reference/reference/place-order.md). # Place Order ## Place orders using the full range of available payment methods (with examples). > Create a new orders and collect payments from shoppers using catalog products (products defined in your Control Panel) or dynamic products (products created via API on the fly).\ > \ > For orders placed with Credit Card, the 3DS Secure flow needs to be covered by redirecting the shoppers to complet the security flow. The full process is detailed \[here]\( > \ > For a full list of list of common errors that may arise when using placing order calls via API version 6 \[here]\( > \ > When placing a new order it generates unique order reference numbers for all orders (purchases). You can use this parameter RefNo sent in the body to retry authorizations for orders with failed transactions by changing the payment method.\ > \ > \*\*UniToken reuse for card payments\*\*: When an order is placed and authorized using a card, the system checks whether a UniToken already exists for that customer (matched on CustomerReference/ExternalCustomerReference plus the card's first 4 and last 4 digits). If a matching UniToken is found, it is updated with the new order reference instead of a new UniToken being generated. The response includes the \`UniToken\` field with the ID of the token that was created or updated. Requires the feature to be enabled at account-level. See \`GET /unitokens/\` to retrieve the list of tokens associated with a customer. ```json {"openapi":"3.0.0","info":{"title":"API REST Documentation","version":"6.0-oas3"},"servers":[{"url":"https://api.2checkout.com/rest/6.0"}],"paths":{"/orders/":{"post":{"tags":["Place order"],"summary":"Place orders using the full range of available payment methods (with examples).","description":"Create a new orders and collect payments from shoppers using catalog products (products defined in your Control Panel) or dynamic products (products created via API on the fly).\n\nFor orders placed with Credit Card, the 3DS Secure flow needs to be covered by redirecting the shoppers to complet the security flow. The full process is detailed [here](https://verifone.cloud/docs/2checkout/API-Integration/01Start-using-the-2Checkout-API/2Checkout-API-general-information/3D-Secure-Flow).\n\nFor a full list of list of common errors that may arise when using placing order calls via API version 6 [here](https://verifone.cloud/docs/2checkout/API-Integration/JSON-RPC_API_6.0/API-6.0-Error-Codes/Error-handling-for-API-6.0).\n\nWhen placing a new order it generates unique order reference numbers for all orders (purchases). You can use this parameter RefNo sent in the body to retry authorizations for orders with failed transactions by changing the payment method.\n\n**UniToken reuse for card payments**: When an order is placed and authorized using a card, the system checks whether a UniToken already exists for that customer (matched on CustomerReference/ExternalCustomerReference plus the card's first 4 and last 4 digits). If a matching UniToken is found, it is updated with the new order reference instead of a new UniToken being generated. The response includes the `UniToken` field with the ID of the token that was created or updated. Requires the feature to be enabled at account-level. See `GET /unitokens/` to retrieve the list of tokens associated with a customer.","parameters":[{"name":"X-Avangate-Authentication","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":true,"style":"simple","explode":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceOrder"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaceOrderResponse"}}}},"400":{"description":"Error","content":{"application/json":{}}},"500":{"description":"Error","content":{"application/json":{}}}}}}},"components":{"schemas":{"PlaceOrder":{"type":"object","properties":{"Language":{"description":"ISO 639-1 two-letter code. Language used for the purchase process. Example: “en.”","type":"string"},"Country":{"description":"Shopper country. ISO 3166 two-letter code. Example: “us.”","type":"string"},"CustomerIP":{"description":"Shopper IP.","type":"string"},"Source":{"description":"The link source for the sale. Replicates the SRC (separate link identifier) parameter in Buy Links. Use the SRC parameter to track sale sources. Maximum length 255 characters. Cannot be null.","type":"string"},"WSOrder":{"description":"The WSOrder parameter is used to control the website URL displayed in the email messages shoppers receive after they place an order. By default, 2Checkout reports the URL set as Homepage in the Account information area. Adding WSOrder to the buy-links for your products will cause the optional website address set by using the parameter to override and replace the Homepage URL in the email notifications sent to customers. The behavior is similar to the WS_ORDER parameter supported on checkout/cart pages and described [here](https://verifone.cloud/docs/2checkout/Documentation/07Commerce/Checkout-links-and-options/Manage-store-URLs-for-shopper-emails).","type":"string"},"ExternalCustomerReference":{"description":"The external customer reference you control. Aggregate subscriptions under the same Customer account if the products they're associated to are purchased by the same shopper by adding the CUSTOMERID (case sensitive) parameter to buy links.","type":"string"},"Currency":{"description":"The currency ISO code for the payment - ISO 4217. Example: usd.","type":"string"},"Promotions":{"description":"Array of promotion codes.","type":"array","items":{"type":"string"}},"Affiliate":{"$ref":"#/components/schemas/orders0_Affiliate"},"Items":{"type":"array","items":{"$ref":"#/components/schemas/PlaceOrder_Items"}},"BillingCycleReset":{"type":"boolean","description":"Only used when the request type is \"Place an order with manual renewal\". Licence renewal will start immediately upon processing the new order, resetting the billing cycle."},"BillingDetails":{"$ref":"#/components/schemas/PlaceOrder_BillingDetails"},"PaymentDetails":{"$ref":"#/components/schemas/PlaceOrder_PaymentDetails"},"ExtraInformation":{"$ref":"#/components/schemas/PlaceOrder_ExtraInformation"}}},"orders0_Affiliate":{"type":"object","properties":{"AffiliateCode":{"description":"The affiliate unique code (as returned by the affiliates API methods).","type":"string"},"AffiliateSource":{"description":"The affiliate source.","type":"string"}}},"PlaceOrder_Items":{"type":"object","properties":{"Code":{"type":"string","description":"The unique code defined for your product."},"RenewalInformation":{"$ref":"#/components/schemas/PlaceOrder_RenewalInformation"},"UpgradeInformation":{"$ref":"#/components/schemas/PlaceOrder_UpgradeInformation"},"Name":{"description":"Product name.","type":"string"},"Description":{"description":"Product description","type":"string"},"Quantity":{"description":"Number of units","type":"string"},"IsDynamic":{"description":"\"Select if the product is dynamic. Possible values:","type":"boolean"},"Tangible":{"description":"true or false, depending on product delivery type.","type":"boolean"},"Fulfillment":{"type":"string"},"PurchaseType":{"description":"\"Possible values:","type":"string"},"Price":{"$ref":"#/components/schemas/PlaceOrder_Price"},"ProductTaxCategoryUUID":{"type":"string"},"PriceType":{"type":"string"},"PriceOptions":{"description":"Array of price option groups.","type":"array","items":{"$ref":"#/components/schemas/PlaceOrder_PriceOptions"}},"CrossSell":{"$ref":"#/components/schemas/PlaceOrder_ItemCrossSell"},"UpSell":{"$ref":"#/components/schemas/PlaceOrder_ItemUpSell"},"RecurringOptions":{"$ref":"#/components/schemas/PlaceOrder_RecurringOptions"},"SubscriptionCustomSettings":{"$ref":"#/components/schemas/Item_SubscriptionCustomSettings"},"Trial":{"$ref":"#/components/schemas/PlaceOrder_TrialInput"},"Promotion":{"$ref":"#/components/schemas/PlaceOrder_ItemPromotion"}}},"PlaceOrder_RenewalInformation":{"type":"object","description":"Used for manual renewal orders.","properties":{"SubscriptionReference":{"type":"string","description":"Unique, system-generated subscription identifier of the subscription that needs to be renewed."},"Code":{"type":"string","description":"The unique code defined for your product. Required for manual renewal only if you wish to change the product on the subscription."},"Quantity":{"type":"string","description":"Number of units. Required for manual renewal only if you wish to change the product quantity on the subscription."}}},"PlaceOrder_UpgradeInformation":{"type":"object","description":"Used for upgrade orders.","properties":{"SubscriptionReference":{"type":"string","description":"Unique, system-generated subscription identifier of the subscription that needs to be upgraded."},"Code":{"type":"string","description":"The unique code defined for your product. Required for upgrade order only if you wish to change the product on the subscription."},"Quantity":{"type":"string","description":"Number of units. Required for upgrade order only if you wish to change the product quantity on the subscription."}}},"PlaceOrder_Price":{"type":"object","properties":{"Amount":{"description":"The price of the product.","type":"integer"},"Type":{"description":"Possible values: NET / GROSS","type":"string"}}},"PlaceOrder_PriceOptions":{"type":"object","properties":{"Name":{"description":"Name of the pricing option group. Mandatory for dynamic products.","type":"string"},"Options":{"description":"Array of pricing options.","type":"array","items":{"$ref":"#/components/schemas/PlaceOrder_Options"}}}},"PlaceOrder_Options":{"type":"object","properties":{"Name":{"description":"Pricing option name. Mandatory for dynamic products.","type":"string"},"Value":{"description":"Pricing option code. Mandatory for catalog products.","type":"string"},"Surcharge":{"description":"Surcharge of the pricing option. For renewal orders, the renewal price includes the pricing option surcharge from the initial order. Mandatory for dynamic products.","type":"integer"}}},"PlaceOrder_ItemCrossSell":{"type":"object","properties":{"ParentCode":{"description":"The product code of the master product you set to trigger the campaign.","type":"string"},"CampaignCode":{"description":"Unique, system-generated identifier for cross-sell campaigns.","type":"integer"},"AutoAdded":{"description":"TRUE/FALSE","type":"boolean"}}},"PlaceOrder_ItemUpSell":{"type":"object","properties":{"ParentCode":{"description":"The product code of the master product you set to trigger the campaign.","type":"string"},"CampaignCode":{"description":"Unique, system-generated identifier for upsell campaigns.","type":"integer"},"PriceOptions":{"type":"array","items":{"description":"Array of price option codes.","type":"string"}},"Quantity":{"description":"Product's quantity","type":"integer"}}},"PlaceOrder_RecurringOptions":{"type":"object","properties":{"CycleLength":{"description":"Billing cycle length. Can be NULL.","type":"integer"},"CycleUnit":{"description":"DAY/MONTH. Can be NULL.","type":"string","enum":["DAY","WEEK","MONTH","YEAR"]},"CycleAmount":{"description":"Billing cycle (renewal) price.","type":"number"},"ContractLength":{"description":"Contract period length (expressed in the specified CycleUnit; must be multiple of CycleLength). Can be NULL.","type":"integer"},"ContractUnit":{"description":"DAY/MONTH. Can be NULL.","type":"string","enum":["DAY","WEEK","MONTH","YEAR","FOREVER"]}}},"Item_SubscriptionCustomSettings":{"type":"object","required":["CycleUnit","CycleLength","CycleAmount","CycleAmountType"],"properties":{"CycleLength":{"description":"Billing cycle length. Can be NULL.","type":"integer","nullable":true,"minimum":1},"CycleUnit":{"description":"DAY/MONTH. Can be NULL.","type":"string","enum":["DAY","MONTH"],"nullable":true},"CycleAmount":{"description":"Billing cycle (renewal) price.","type":"number","format":"float","minimum":0,"exclusiveMinimum":true},"CycleAmountType":{"description":"Billing cycle unit NET/GROSS.","type":"string","enum":["NET","GROSS"]}}},"PlaceOrder_TrialInput":{"type":"object","properties":{"Period":{"description":"The length of the trial subscription lifetime in days.","type":"integer"},"Price":{"description":"Total trial price in the payment currency before 2Checkout deducts any taxes, discounts, etc.","type":"number"}}},"PlaceOrder_ItemPromotion":{"type":"object","properties":{"Code":{"description":"Promotion code","type":"string"}}},"PlaceOrder_BillingDetails":{"required":["Address1","City","CountryCode","Email","FirstName","LastName","State","Zip"],"type":"object","properties":{"Address1":{"description":"Shopper address.","type":"string"},"City":{"description":"Shopper city.","type":"string"},"State":{"description":"The state in the shopper's country. Mandatory when you set the Billing Country to US, Canada, Brazil, Turkey, India and Romania. Use case insensitive utf8 strings for the full name, or just the two letter code.","type":"string"},"CountryCode":{"description":"Shopper country. ISO 3166 two-letter code.","type":"string"},"Email":{"description":"Shopper email address.","type":"string"},"FirstName":{"description":"Shopper name.","type":"string"},"LastName":{"description":"Shopper surname.","type":"string"},"Zip":{"description":"ZIP/ Postal code.","type":"string"}}},"PlaceOrder_PaymentDetails":{"required":["Currency","Type"],"type":"object","properties":{"Type":{"description":"\"The payment method:","type":"string"},"Currency":{"type":"string","description":"The currency ISO code for the payment - ISO 4217. Can be changed for the method \"Place an order with manual renewal\" to set a common currency for multiple subscriptions renewed via the same order."},"CustomerIP":{"description":"Shopper IP.","type":"string"},"UniToken":{"type":"string","description":"The UUID of a previously issued UniToken to use as the payment method. Required when Type is UNITOKEN. When an order is placed and authorized with a card and a UniToken already exists for the same customer (matched on CustomerReference/ExternalCustomerReference plus the card's first 4 and last 4 digits), that UniToken is updated with the new order reference and its ID is returned in the response, instead of a new UniToken being created."},"PaymentMethod":{"$ref":"#/components/schemas/PlaceOrder_PaymentDetails_PaymentMethod"}}},"PlaceOrder_PaymentDetails_PaymentMethod":{"type":"object","properties":{"CardNumber":{"description":"The credit/debit card number.","type":"string"},"CardType":{"description":"visa, visaelectron, mastercard, maestro, amex, discover, dankort, cartebleue, jcb, hipercard, elo","type":"string"},"Vendor3DSReturnURL":{"description":"URL address to which customers are redirected after the 3DS details get validated by the bank and the order is successfully authorized.","type":"string"},"Vendor3DSCancelURL":{"description":"URL address to which customers are redirected if the 3DS details were not validated or the order could not be authorized.","type":"string"},"ExpirationYear":{"description":"The year in which the card expires.","type":"string"},"ExpirationMonth":{"description":"The month in which the card expires.","type":"string"},"CCID":{"description":"Credit Card Identification - an extra ID printed on the card, usually a 3-4 digit number, the CVC2/CVV2.","type":"string"},"HolderName":{"description":"Cardholder name.","type":"string"},"RecurringEnabled":{"description":"\"• true – shopper checks the auto-renewal checkbox and 2Checkout charges subscription renewals using a recurring billing process.","type":"boolean"},"HolderNameTime":{"description":"The interval of time in seconds in which shoppers enter their name in the HolderName field. An abnormally short interval is usually a red flag for fraud attempts. Can be NULL, but not a negative number.","type":"integer"},"CardNumberTime":{"description":"The interval of time in seconds in which shopper enters their card number in the CardNumber field. An abnormally short interval is usually a red flag for fraud attempts.","type":"integer"}}},"PlaceOrder_ExtraInformation":{"type":"object","properties":{"RetryFailedPaymentLink":{"type":"string","format":"url","description":"One of the url query params must be \"[REFNO]\""},"ProposalId":{"description":"The unique merchant proposal ID generated by the 2Checkout system.","type":"string","maximum":36},"PurchaseOrderDownloadLink":{"description":"Purchase order download link","type":"string","format":"url"},"AssistedSale":{"description":"True/False","type":"boolean"},"AssistedSaleAccountManagerEmail":{"description":"Account manager email","type":"string"}}},"PlaceOrderResponse":{"type":"object","description":"The order that was created (or updated, for a retry/resume). Field availability can vary slightly by payment method - see the response examples on the operation for the full, method-specific payloads.","properties":{"RefNo":{"type":"string","description":"Unique order reference number."},"OrderNo":{"type":"integer"},"ExternalReference":{"type":"string"},"Status":{"type":"string","description":"The status of the order (e.g. AUTHRECEIVED, PENDING, COMPLETE)."},"ApproveStatus":{"type":"string"},"VendorApproveStatus":{"type":"string"},"UniToken":{"type":"string","description":"The ID of the UniToken associated with this order. Present on orders authorized with a card (directly or via a stored UniToken). If a UniToken already existed for the customer and card (matched on CustomerReference/ExternalCustomerReference plus the card's first 4 and last 4 digits), that same UniToken is updated with this order's reference and returned here instead of a new one being created."},"Language":{"type":"string"},"Source":{"type":"string"},"WSOrder":{"type":"string"},"OrderDate":{"type":"string"}},"additionalProperties":true}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.2checkout.com/api-reference/reference/place-order.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.