--- title: "Create a new order" method: POST path: "/v1/orders" tags: ["Order"] --- # Create a new order `POST /v1/orders` ## Request body - Order — A Reach order, representing a payment attempt. See https://docs.withreach.com/docs/states-and-events for information on the order lifecycle. If created by a session, the presence indicates the session is completed and the payment is being processed. - `OrderId` string, uuid, required — UUID identifying the individual Order. - `SessionId` string, uuid — UUID representing the Session - `State` 'AUTHENTICATING' | 'PENDING' | 'PROCESSING' | 'PAYMENTAUTHORIZED' | 'PROCESSED' | 'PROCESSINGFAILED' | 'CANCELLED' | 'DECLINED', required — Order state. See: https://docs.withreach.com/docs/states-and-events - `MerchantReference` string, required — Unique identifier provided by merchant. - `BillingProfile` BillingProfile — Billing details associated with the payment. Some fields may be required or optional depending on the Country in BillingProfile.Address. See: https://docs.withreach.com/reference/country-specific-fields-1 - `BillingProfileId` string — A UUID for a given BillingProfile object present in Reach. This can be used later to reference an existing consumer - `BillingProfileReference` string — A unique merchant-supplied consumer identifier. If supplied, this can be used later to reference an existing consumer. - `Name` string, required — Customer’s given name. - `Company` string — Customer's company name. - `Email` string, required — Customer’s email address - `Address` Address, required — A postal address used for tax jurisdiction determination. - `Street` string, required — Street address line. - `City` string, required — City name. - `Region` string — State, province, or region code (e.g. `"CA"` for California, `"NSW"` for New South Wales). Recommended for US and Canadian addresses. - `Country` string, required — ISO 3166-1 alpha-2 country code. - `Postcode` string — Postal or ZIP code. - `Phone` string — Customer's phone number. - `Birthdate` string — Customer's birthdate (format yyyy-MM-dd). Required depending on the Country. - `NationalIdentifier` string — National ID, such as SSN or CPF. Required depending on the Country. - `BillingProfileId` string, uuid — Corresponds to the BillingProfileId returned in a BillingProfile. Can be passed in to reference an existing billing profile instead of creating a new one. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required. - `BillingProfileReference` string — Merchant supplied reference that uniquely maps to a BillingProfile. Can be passed in to reference an existing BillingProfile. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required. - `Currency` string — Three-character ISO-4217 currency code used to process the payment. - `Items` Item[] — List of items to be paid. At least one Item must be supplied in requests. The sum total of the item amounts will be added to the TotalAmount - `Id` string — Line item identifier. - `Sku` string, required — Field to identify a line item within the tax system. - `Description` string — Description of a line item. - `TaxCode` string — Tax code for the line item. - `TaxIncluded` boolean — Indicates if a line item has tax included. - `Amount` number, float, required — Amount of item to be paid. Currency is defined by the parent object. - `TaxAmount` number, float — Amount of tax calculated for this item. - `Tax` Tax[] — List of taxes applied for the item. - `Name` string — Name of the tax. - `Type` string — Type of tax. - `TaxAmount` number, float — Amount of tax calculated of this tax type. - `Payment` Payment — Object representing the payment information for an order - `Type` 'CARD' | 'ONLINE' | 'OFFLINE' — Payment classification - `Method` string — Specific payment method as returned in Name of getPaymentMethods. See: https://docs.withreach.com/reference/getpaymentmethods - `ReturnUrl` string — Merchant URL to redirect a user to upon completion at a third party payment processor or a 3DS challenge. This may contain "{SessionId}" anywhere in the string to have the SessionId embedded in the url. - `Online` Online — Contains payment details for Online payment types. - `Locale` string — Locale for redirects. May need to be customized to a specific payment type. - `Ideal` Ideal — Payment details specific to iDeal. - `IssuerId` string — iDeal-specific Issuer ID, to be passed to the processor - `Paypal` Paypal — Payment details specific to PayPal. - `Email` string — Email associated with the customer's PayPal account, as they entered in a redirect - `Card` Card — Payment details for Card type. Must be supplied if Payment.Type is CARD - `StashId` string — Details of a card payment returned from a stash call. See: https://docs.withreach.com/docs/stash - `Bin` string — First 6 digits of a card number. Used for display purposes - `LastFour` string — Last 4 digits of a card number. Used for display purposes. - `Expiry` Expiry — Card expiry information - `Month` string — Month the card expires in. Returned as 2-character numeric. - `Year` string — Year the card expires. Returned as a 4-character numeric. - `Offline` Offline — Offline payment information. - `ContractId` string, uuid — Reach-generated ID of an existing contract. Can be supplied in lieu of a Payment object. Will be returned in the response if OpenContract is set to true. - `DeviceFingerprint` string — Device fingerprint - see https://docs.withreach.com/reference/fingerprint-1 - `Discounts` Discount[] — List of discounts. The sum of the discounts amounts will be subtracted from the TotalAmount - `Name` string, required — A free-text name to describe the discount - `Amount` number, float, required — Flat amount of the discount to be applied. - `ShippingDetails` ShippingDetails — Customer's shipping details. This is required if physical goods are shipped along with the order. - `ShippingAmount` number — Total amount excluding taxes and duties. Currency is defined by parent object. - `DutyAmount` number — Duty for the entire order. Currency is defined by parent object. - `Name` string, required — Customer’s given name. - `Company` string — Company's name. - `Email` string — Customer’s email address - `Address` Address, required — A postal address used for tax jurisdiction determination. - `Street` string, required — Street address line. - `City` string, required — City name. - `Region` string — State, province, or region code (e.g. `"CA"` for California, `"NSW"` for New South Wales). Recommended for US and Canadian addresses. - `Country` string, required — ISO 3166-1 alpha-2 country code. - `Postcode` string — Postal or ZIP code. - `TaxAmount` number — Tax to be applied to the order. In the consumer currency, max precision of 2 digits. TaxAmount will be added to the TotalAmount. - `ViaAgent` boolean — Indicates that this order is being made by an agent, and not the end consumer. If false or not present, the order is assumed to be placed by the end consumer. - `AcceptLiability` boolean — If true, the merchant accepts financial liability for this order. - `AutoCapture` boolean — If true or the payment method used by the consumer does not support pre-authorization, the payment will be completed. If false or not present, and the payment method supports pre-authorization, the order will be left in the PaymentAuthorized state and the merchant must capture the order using a capture request. - `OpenContract` boolean — If true, a contract (used for recurring billing, subscriptions, stored payment options, etc.) will be opened if possible. If false or not present, the order will not open a contract. - `TaxQuoteId` string — Unique Tax Quote Id provided by merchant, Id recieved from calling the Reach Quote API. - `Meta` Meta — Any optional metadata to be included. Can be a simple reference ID or some complex object containing multiple values, as long as it is valid JSON. - `UnderReview` boolean — This will be returned as true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed. - `Chargeback` boolean — This will be returned as true if a chargeback has been issued against the order. An outstanding chargeback disables the ability to submit a refund against the order. - `Reason` string — Gives a reason for an order to be in a given state. - `Expiry` string — If the order was created with Capture false, and the payment is authorized, the RFC 3339 time at which this order expires. If further authentication is required, this is the time by which that authentication must be completed. - `Action` Action — If additional action must be taken to proceed with a request, this object contains information about the required action. - `Redirect` string — URL to redirect a consumer on completion - `Challenge` string — The URL to use for iframe-embedded authentication (ex. 3-DSecure v2, WeChat QR code, etc.) - `Display` Display — A freeform JSON object which, in the context of the specified request, gives the necessary information for a consumer to proceed. See https://docs.withreach.com/docs/display-parameters. - `AccountHolder` string - `AccountNumber` string - `BankName` string - `City` string - `Iban` string - `PaymentReference` string - `SwiftCode` string - `ExtraBankData` string - `Times` Times — Gives times of various order state transitions - `Created` string — The RFC 3339 timestamp at which the order was created. - `Authorized` string — The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto). - `Processed` string — The RFC 3339 timestamp at which the order's payment was processed. This will be null if the order's payment has not been processed yet or has failed to be processed. - `AdminUrl` string — A link to this order in the Reach admin app. You must have valid credentials to view ## Response `200` Operation successful - Order — A Reach order, representing a payment attempt. See https://docs.withreach.com/docs/states-and-events for information on the order lifecycle. If created by a session, the presence indicates the session is completed and the payment is being processed. - `OrderId` string, uuid, required — UUID identifying the individual Order. - `SessionId` string, uuid — UUID representing the Session - `State` 'AUTHENTICATING' | 'PENDING' | 'PROCESSING' | 'PAYMENTAUTHORIZED' | 'PROCESSED' | 'PROCESSINGFAILED' | 'CANCELLED' | 'DECLINED', required — Order state. See: https://docs.withreach.com/docs/states-and-events - `MerchantReference` string, required — Unique identifier provided by merchant. - `BillingProfile` BillingProfile — Billing details associated with the payment. Some fields may be required or optional depending on the Country in BillingProfile.Address. See: https://docs.withreach.com/reference/country-specific-fields-1 - `BillingProfileId` string — A UUID for a given BillingProfile object present in Reach. This can be used later to reference an existing consumer - `BillingProfileReference` string — A unique merchant-supplied consumer identifier. If supplied, this can be used later to reference an existing consumer. - `Name` string, required — Customer’s given name. - `Company` string — Customer's company name. - `Email` string, required — Customer’s email address - `Address` Address, required — A postal address used for tax jurisdiction determination. - `Street` string, required — Street address line. - `City` string, required — City name. - `Region` string — State, province, or region code (e.g. `"CA"` for California, `"NSW"` for New South Wales). Recommended for US and Canadian addresses. - `Country` string, required — ISO 3166-1 alpha-2 country code. - `Postcode` string — Postal or ZIP code. - `Phone` string — Customer's phone number. - `Birthdate` string — Customer's birthdate (format yyyy-MM-dd). Required depending on the Country. - `NationalIdentifier` string — National ID, such as SSN or CPF. Required depending on the Country. - `BillingProfileId` string, uuid — Corresponds to the BillingProfileId returned in a BillingProfile. Can be passed in to reference an existing billing profile instead of creating a new one. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required. - `BillingProfileReference` string — Merchant supplied reference that uniquely maps to a BillingProfile. Can be passed in to reference an existing BillingProfile. Exactly one of BillingProfile, BillingProfileId or BillingprofileReference are required. - `Currency` string — Three-character ISO-4217 currency code used to process the payment. - `Items` Item[] — List of items to be paid. At least one Item must be supplied in requests. The sum total of the item amounts will be added to the TotalAmount - `Id` string — Line item identifier. - `Sku` string, required — Field to identify a line item within the tax system. - `Description` string — Description of a line item. - `TaxCode` string — Tax code for the line item. - `TaxIncluded` boolean — Indicates if a line item has tax included. - `Amount` number, float, required — Amount of item to be paid. Currency is defined by the parent object. - `TaxAmount` number, float — Amount of tax calculated for this item. - `Tax` Tax[] — List of taxes applied for the item. - `Name` string — Name of the tax. - `Type` string — Type of tax. - `TaxAmount` number, float — Amount of tax calculated of this tax type. - `Payment` Payment — Object representing the payment information for an order - `Type` 'CARD' | 'ONLINE' | 'OFFLINE' — Payment classification - `Method` string — Specific payment method as returned in Name of getPaymentMethods. See: https://docs.withreach.com/reference/getpaymentmethods - `ReturnUrl` string — Merchant URL to redirect a user to upon completion at a third party payment processor or a 3DS challenge. This may contain "{SessionId}" anywhere in the string to have the SessionId embedded in the url. - `Online` Online — Contains payment details for Online payment types. - `Locale` string — Locale for redirects. May need to be customized to a specific payment type. - `Ideal` Ideal — Payment details specific to iDeal. - `IssuerId` string — iDeal-specific Issuer ID, to be passed to the processor - `Paypal` Paypal — Payment details specific to PayPal. - `Email` string — Email associated with the customer's PayPal account, as they entered in a redirect - `Card` Card — Payment details for Card type. Must be supplied if Payment.Type is CARD - `StashId` string — Details of a card payment returned from a stash call. See: https://docs.withreach.com/docs/stash - `Bin` string — First 6 digits of a card number. Used for display purposes - `LastFour` string — Last 4 digits of a card number. Used for display purposes. - `Expiry` Expiry — Card expiry information - `Month` string — Month the card expires in. Returned as 2-character numeric. - `Year` string — Year the card expires. Returned as a 4-character numeric. - `Offline` Offline — Offline payment information. - `ContractId` string, uuid — Reach-generated ID of an existing contract. Can be supplied in lieu of a Payment object. Will be returned in the response if OpenContract is set to true. - `DeviceFingerprint` string — Device fingerprint - see https://docs.withreach.com/reference/fingerprint-1 - `Discounts` Discount[] — List of discounts. The sum of the discounts amounts will be subtracted from the TotalAmount - `Name` string, required — A free-text name to describe the discount - `Amount` number, float, required — Flat amount of the discount to be applied. - `ShippingDetails` ShippingDetails — Customer's shipping details. This is required if physical goods are shipped along with the order. - `ShippingAmount` number — Total amount excluding taxes and duties. Currency is defined by parent object. - `DutyAmount` number — Duty for the entire order. Currency is defined by parent object. - `Name` string, required — Customer’s given name. - `Company` string — Company's name. - `Email` string — Customer’s email address - `Address` Address, required — A postal address used for tax jurisdiction determination. - `Street` string, required — Street address line. - `City` string, required — City name. - `Region` string — State, province, or region code (e.g. `"CA"` for California, `"NSW"` for New South Wales). Recommended for US and Canadian addresses. - `Country` string, required — ISO 3166-1 alpha-2 country code. - `Postcode` string — Postal or ZIP code. - `TaxAmount` number — Tax to be applied to the order. In the consumer currency, max precision of 2 digits. TaxAmount will be added to the TotalAmount. - `ViaAgent` boolean — Indicates that this order is being made by an agent, and not the end consumer. If false or not present, the order is assumed to be placed by the end consumer. - `AcceptLiability` boolean — If true, the merchant accepts financial liability for this order. - `AutoCapture` boolean — If true or the payment method used by the consumer does not support pre-authorization, the payment will be completed. If false or not present, and the payment method supports pre-authorization, the order will be left in the PaymentAuthorized state and the merchant must capture the order using a capture request. - `OpenContract` boolean — If true, a contract (used for recurring billing, subscriptions, stored payment options, etc.) will be opened if possible. If false or not present, the order will not open a contract. - `TaxQuoteId` string — Unique Tax Quote Id provided by merchant, Id recieved from calling the Reach Quote API. - `Meta` Meta — Any optional metadata to be included. Can be a simple reference ID or some complex object containing multiple values, as long as it is valid JSON. - `UnderReview` boolean — This will be returned as true if a fraud review is in progress for the order. Payment cannot be processed until the review has been completed. - `Chargeback` boolean — This will be returned as true if a chargeback has been issued against the order. An outstanding chargeback disables the ability to submit a refund against the order. - `Reason` string — Gives a reason for an order to be in a given state. - `Expiry` string — If the order was created with Capture false, and the payment is authorized, the RFC 3339 time at which this order expires. If further authentication is required, this is the time by which that authentication must be completed. - `Action` Action — If additional action must be taken to proceed with a request, this object contains information about the required action. - `Redirect` string — URL to redirect a consumer on completion - `Challenge` string — The URL to use for iframe-embedded authentication (ex. 3-DSecure v2, WeChat QR code, etc.) - `Display` Display — A freeform JSON object which, in the context of the specified request, gives the necessary information for a consumer to proceed. See https://docs.withreach.com/docs/display-parameters. - `AccountHolder` string - `AccountNumber` string - `BankName` string - `City` string - `Iban` string - `PaymentReference` string - `SwiftCode` string - `ExtraBankData` string - `Times` Times — Gives times of various order state transitions - `Created` string — The RFC 3339 timestamp at which the order was created. - `Authorized` string — The RFC 3339 timestamp at which the order’s payment was authorized. This will be null if the payment has not yet been authorized or the payment method used for the order does not support pre-authorization (eg. Boleto). - `Processed` string — The RFC 3339 timestamp at which the order's payment was processed. This will be null if the order's payment has not been processed yet or has failed to be processed. - `AdminUrl` string — A link to this order in the Reach admin app. You must have valid credentials to view ## Other responses - `201` — Success. Possibly returned if the full order information could not be retrieved. - `400` — Invalid request - `401` — Authentication Required - `403` — Unauthorized - `415` — Unsupported Media Type - `500` — Any unexpected Server error --- [API](https://skmtc.net/withreach/apis/reach-checkout-api.md) · [All operations](https://skmtc.net/withreach/apis/reach-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/withreach/reach-checkout-api/versions/f95f4b8dd180/schema)