Make a purchase

Executes a purchase.

A purchase can be completed both with and without authentication. Purchases that use a pre-created payment instrument must use authentication.

To preview the purchase before completing it, use the Purchase preview operation.

SecurityCustomerJWT or PublishableApiKey
Request
Request Body schema: application/json
websiteId
required
string <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

required
Payment token (object) or Payment instrument (object) or Payment Methods (object) or Payment card (object) or Bank account (object)

Payment instruction for the purchase.

One of:

Payment instruction for the purchase.

token
required
string

Token ID of the payment.

required
Array of objects non-empty
Array (non-empty)
planId
required
string <= 50 characters

ID of the plan.

quantity
integer

Number of product units in the specified plan.

object or null

Billing address details.

firstName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's first name.

lastName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's last name.

organization
string or null <= 255 characters ^[\w\s\-\p{L},.'&]+$

Contact's organization.

address
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

First line of the contact's street address.

address2
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

Second line of the contact's street address.

city
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's city of residence.

region
string or null <= 45 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's region of residence.

country
string or null <= 2 characters ^[A-Z]{2}$

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies if the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies if the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

jobTitle
string or null <= 255 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's job title.

object or null

Delivery address details.

firstName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's first name.

lastName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's last name.

organization
string or null <= 255 characters ^[\w\s\-\p{L},.'&]+$

Contact's organization.

address
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

First line of the contact's street address.

address2
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

Second line of the contact's street address.

city
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's city of residence.

region
string or null <= 45 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's region of residence.

country
string or null <= 2 characters ^[A-Z]{2}$

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array
label
required
string <= 45 characters

Phone number label or name.

value
required
string <= 50 characters

Phone number value.

primary
boolean

Specifies if the phone number is the contact's primary phone number.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

Array
label
required
string <= 45 characters

Email label or name.

value
required
string <email> <= 255 characters

Email address value.

primary
boolean

Specifies if the email address is the contact's primary email address.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

jobTitle
string or null <= 255 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's job title.

shippingRateId
string <= 50 characters

ID of the shipping rate. If this value is not set, the cheapest applicable shipping rate is chosen.

couponIds
Array of strings

List of coupons that are applied to the order.

password
string or null

Customer account password. If this value is set, it is used to create a customer account.

redirectUrl
string or null <uri>

URL to redirect the end-user when an offsite transaction is completed. If website.url is https://example.com, then the redirectUrl can be set to one the following:

  • https://example.com

  • https://example.com/some/path

  • https://example.com/some/path?and=query

  • https://example.com/some/path?and=query#and-fragment

This field defaults to the configured website URL. You may use {id} or {result} as placeholders in the URL. These placeholders are replaced with the transaction ID and result.

Responses
201

Order created.

Response Headers
Location
string <uri>

Location of the related resource.

Example: "https://api.rebilly.com/example"
Response Schema: application/json
orderId
string <= 50 characters

ID of the order.

object (StorefrontInvoice)

Initial invoice.

currency
required
string = 3 characters

Currency code in ISO 4217 format.

websiteId
required
string (WebsiteId) <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

id
string <= 50 characters

ID of the invoice.

invoiceNumber
integer

Auto-incrementing number based on the sequence of invoices for any particular customer.

subscriptionId
string <= 50 characters

ID of the related subscription order, if available. This field is null if there are no related subscription orders.

amount
number <double>

Amount of the invoice.

amountDue
number <double>

Amount that is due on the invoice.

subtotalAmount
number <double>

Subtotal amount of the invoice.

discountAmount
number <double>

Discount amount that is applied to the invoice.

object (Shipping)

Shipping settings.

amount
required
integer

Shipping amount.

calculator
required
string

Shipping calculator.

object (InvoiceTax)

Invoice taxes.

calculator
required
string

Type of tax calculator.

required
Array of objects (InvoiceTaxItem)

Taxes applied to this invoice.

object

Billing address of the invoice.

firstName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's first name.

lastName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's last name.

organization
string or null <= 255 characters ^[\w\s\-\p{L},.'&]+$

Contact's organization.

address
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

First line of the contact's street address.

address2
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

Second line of the contact's street address.

city
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's city of residence.

region
string or null <= 45 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's region of residence.

country
string or null <= 2 characters ^[A-Z]{2}$

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

jobTitle
string or null <= 255 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

object

Delivery address of the invoice.

firstName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's first name.

lastName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's last name.

organization
string or null <= 255 characters ^[\w\s\-\p{L},.'&]+$

Contact's organization.

address
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

First line of the contact's street address.

address2
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

Second line of the contact's street address.

city
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's city of residence.

region
string or null <= 45 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's region of residence.

country
string or null <= 2 characters ^[A-Z]{2}$

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

jobTitle
string or null <= 255 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

poNumber
string or null

Purchase order number that is displayed on the invoice.

notes
string

Notes for the customer that are displayed on the invoice.

Array of objects (InvoiceItem)

Invoice items array.

Array
type
required
string

Type of invoice item.

Enum: "debit" "credit"
unitPrice
required
number <double>

Unit price of the invoice item.

id
string <= 50 characters

ID of the website. A website is where an organization obtains a customer through a subscription. For more information, see Obtain an organization ID and website ID.

description
string <= 1000 characters

Description of the invoice item.

quantity
integer

Quantity of the invoice item.

price
number <double>

Total price of the invoice item.

productId
string <= 50 characters

ID of the product.

discountAmount
number <double>

Discount amount applied to the invoice item.

periodStartTime
string <date-time>

Date and time when the billing period starts.

periodEndTime
string <date-time>

Date and time when the billing period ends.

periodNumber
integer

Number of subscription order billing periods in which the invoice item has been included.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

object (InvoiceTaxItem)

Invoice item tax.

Array of objects

Related links.

object

Embedded objects that are requested by the expand query parameter.

Array of objects

Discounts applied.

Array
couponId
string <= 50 characters

ID of the coupon.

redemptionId
string <= 50 characters

ID of the redemption.

amount
number <double>

Total amount discounted by this coupon.

description
string

Description of the discount.

context
string (DiscountContext)
Default: "items"

Context in which the discount applies.

Enum: Description
items

items (less discounts)

shipping

shipping (less discounts)

items-and-shipping

items and shipping (less discounts)

autopayScheduledTime
string <date-time>

Date and time when an automatic payment (autopay) is scheduled.

autopayRetryNumber
integer >= 0
Default: 0

Number of times that an automatic payment (autopay) has been attempted on an invoice.

status
string

Status of the invoice.

Enum: "draft" "unpaid" "paid" "partially-paid" "past-due" "abandoned" "voided" "partially-refunded" "refunded" "disputed"
delinquentCollectionPeriod
integer

Length of time, in days, between when the invoice is due and when the invoice is paid.

collectionPeriod
integer

Length of time, in days, between when the invoice is issued and when the invoice is paid.

abandonedTime
string <date-time>

Date and time when the invoice is abandoned.

voidedTime
string <date-time>

Date and time when the invoice is voided.

paidTime
string <date-time>

Date and time when the invoice is paid.

dueTime
string <date-time>

Date and time when the invoice is due for payment.

issuedTime
string <date-time>

Date and time when the invoice is issued.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

paymentFormUrl
string <url>

URL where the customer is redirected to pay the invoice using one of the methods which are available to the customer. This is an alternative to creating a new transaction with empty methods.

Array of objects (StorefrontTransaction)

Invoice transactions array.

Array
id
string <= 50 characters

ID of the transaction.

websiteId
string <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

customerId
string <= 50 characters

ID of the customer resource.

type
string

Type of transaction.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Status of the transaction.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Result of the transaction.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

Total amount of the transaction.

currency
string = 3 characters

Currency code in ISO 4217 format.

purchaseAmount
number <double>

Amount by which the purchase is completed. If an adjustment occurs, the purchased amount may differ from the requested amount.

purchaseCurrency
string = 3 characters

Currency code in ISO 4217 format.

requestAmount
number <double>

Amount of the payment request. If an adjustment occurs, the purchase amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string or null <= 50 characters

ID of the parent transaction.

childTransactions
Array of strings (ResourceId)

IDs of child transactions.

invoiceIds
Array of strings (ResourceId)

Related invoice IDs.

subscriptionIds
Array of strings (ResourceId)

Subscription IDs of invoices that are related to the transaction.

planIds
Array of strings (ResourceId)

Plan IDs of orders that are related to the transaction.

isRebill
boolean

Specifies if the transaction is one of a number of recurring payments in a subscription, excluding trials or setup fees.

rebillNumber
integer

Rebill number of the transaction. A rebill number is the number of recurring payments in a subscription, excluding trials or setup fees.

object

Billing address.

has3ds
boolean

Specifies if the transaction uses 3D Secure.

object

Authentication object.

redirectUrl
string or null <uri>

URL where the end-user is redirected to when an offsite transaction is completed. The default value is the website URL.

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies if a transaction is a retry.

billingDescriptor
string or null

Billing descriptor that appears on the periodic billing statement. For a credit card statement, this field commonly contains 12 or fewer characters.

description
string <= 255 characters

Description of the payment.

requestId
string

Request ID of the transaction. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

Specifies if the transaction has amount adjustment.

gatewayName
string or null

Name of the payment gateway that processed, or is selected to process, the transaction. This value is only available after a gateway is selected for the transaction.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 170 more
customFields
object (ResourceCustomFields)
Default: {}

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

processedTime
string <date-time>

Date and time when the transaction is processed.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

object (InstrumentReference)

Default payment instrument information.

approvalUrl
string <uri>

URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

Session's token used for authentication. It would allow to visit created order, invoice and transaction.

Array of objects

Related links.

Array of objects (SelfLink)

Related links.

Array
href
string

Link URL.

rel
string

Type of link.

Value: "self"
object (StorefrontTransaction)

Initial transaction.

id
string <= 50 characters

ID of the transaction.

websiteId
string <= 50 characters

ID of the website. A website is where an organization obtains a customer. For more information, see Obtain an organization ID and website ID.

customerId
string <= 50 characters

ID of the customer resource.

type
string

Type of transaction.

Enum: "3ds-authentication" "authorize" "capture" "credit" "refund" "sale" "setup" "void"
status
string

Status of the transaction.

Enum: "completed" "conn-error" "disputed" "never-sent" "offsite" "partially-refunded" "pending" "refunded" "sending" "suspended" … 6 more
result
string

Result of the transaction.

Enum: "abandoned" "approved" "canceled" "declined" "unknown"
amount
number <double>

Total amount of the transaction.

currency
string = 3 characters

Currency code in ISO 4217 format.

purchaseAmount
number <double>

Amount by which the purchase is completed. If an adjustment occurs, the purchased amount may differ from the requested amount.

purchaseCurrency
string = 3 characters

Currency code in ISO 4217 format.

requestAmount
number <double>

Amount of the payment request. If an adjustment occurs, the purchase amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string or null <= 50 characters

ID of the parent transaction.

childTransactions
Array of strings (ResourceId)

IDs of child transactions.

invoiceIds
Array of strings (ResourceId)

Related invoice IDs.

subscriptionIds
Array of strings (ResourceId)

Subscription IDs of invoices that are related to the transaction.

planIds
Array of strings (ResourceId)

Plan IDs of orders that are related to the transaction.

isRebill
boolean

Specifies if the transaction is one of a number of recurring payments in a subscription, excluding trials or setup fees.

rebillNumber
integer

Rebill number of the transaction. A rebill number is the number of recurring payments in a subscription, excluding trials or setup fees.

object

Billing address.

firstName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's first name.

lastName
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's last name.

organization
string or null <= 255 characters ^[\w\s\-\p{L},.'&]+$

Contact's organization.

address
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

First line of the contact's street address.

address2
string or null <= 60 characters ^[\w\s\-\/\p{L},.#;:()'&]+$

Second line of the contact's street address.

city
string or null <= 45 characters ^[\w\s\-\p{L},.']+$

Contact's city of residence.

region
string or null <= 45 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's region of residence.

country
string or null <= 2 characters ^[A-Z]{2}$

Contact's country of residence in ISO 3166 alpha-2 country code. For examples, see ISO.org.

postalCode
string or null <= 10 characters ^[\w\s\-]+$

Contact's postal code.

Array of objects (ContactPhoneNumbers)

List of phone numbers associated with the contact.

Array of objects (ContactEmails)

List of email addresses associated with the contact.

dob
string or null <date>

Contact's date of birth in ISO-8601 YYYY-MM-DD format.

jobTitle
string or null <= 255 characters ^[\w\s\-\/\p{L},.#;:()']+$

Contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

has3ds
boolean

Specifies if the transaction uses 3D Secure.

object

Authentication object.

server
string

Name of the 3D Secure server.

version
string

Version of 3D Secure.

Enum: "1.0.2" "2.1.0" "2.2.0"
enrolled
string

Specifies if the cardholder is enrolled in 3D Secure.

Enum: "yes" "no" "invalid card/timeout" "unavailable"
authenticated
string

Authentication response status for 3D Secure.

Enum: "yes" "no" "not applicable" "attempted"
liability
string
Enum: "protected" "not protected" "protected (attempt)"
flow
string

Authentication flow for 3D Secure 2.

Enum: "frictionless" "challenge"
isDowngraded
boolean
Deprecated
Default: false

Specifies if 3D Secure 2 is attempted and downgraded to 3D Secure 1.

redirectUrl
string or null <uri>

URL where the end-user is redirected to when an offsite transaction is completed. The default value is the website URL.

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies if a transaction is a retry.

billingDescriptor
string or null

Billing descriptor that appears on the periodic billing statement. For a credit card statement, this field commonly contains 12 or fewer characters.

description
string <= 255 characters

Description of the payment.

requestId
string

Request ID of the transaction. This ID must be unique within a 24 hour period. Use this field to prevent duplicated transactions.

hasAmountAdjustment
boolean

Specifies if the transaction has amount adjustment.

gatewayName
string or null

Name of the payment gateway that processed, or is selected to process, the transaction. This value is only available after a gateway is selected for the transaction.

Enum: "A1Gateway" "ACI" "Adyen" "Airpay" "AmazonPay" "AmexVPC" "ApcoPay" "AsiaPaymentGateway" "AstroPayCard" "AuthorizeNet" … 170 more
customFields
object (ResourceCustomFields)
Default: {}

Use custom fields to extend a resource scheme to include custom data that is not provided as a common field. For more information, see Custom fields.

processedTime
string <date-time>

Date and time when the transaction is processed.

createdTime
string <date-time> (CreatedTime)

Date and time which is set automatically when the resource is created.

updatedTime
string <date-time> (UpdatedTime)

Date and time which updates automatically when the resource is updated.

object (InstrumentReference)

Default payment instrument information.

method
required
string (PaymentMethod)

Payment method.

Enum: "payment-card" "ach" "cash" "check" "paypal" "AdvCash" "Airpay" "Alfa-click" "Alipay" "AmazonPay" … 165 more
paymentInstrumentId
string <= 50 characters

ID of the payment instrument.

approvalUrl
string <uri>

URL to redirect the end-customer when transaction status is waiting-approval or offsite.

token
string

Session's token used for authentication. It would allow to visit created order, invoice and transaction.

Array of objects

Related links.

Array
href
string

Link URL.

rel
string

Type of link.

Enum: "self" "approvalUrl"
token
string

Session token that is used for authentication. This token can be used to view the created order, invoice, and transaction.

401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

422

Invalid data sent.

post/storefront/purchase
Request samples
application/json
{
  • "websiteId": "web_0YV7DE4Z26DQSA1AC92FBJ7SEG",
  • "items": [
    ],
  • "billingAddress": {
    },
  • "deliveryAddress": {
    },
  • "shippingRateId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "paymentInstruction": {
    },
  • "couponIds": [
    ],
  • "password": "string",
  • "redirectUrl": "http://example.com"
}
Response samples
application/json
{
  • "orderId": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "invoice": {
    },
  • "transaction": {
    },
  • "token": "string"
}