Make a purchase

Purchase can be accomplished both with and without Authentication. Purchase via pre-created Payment Instrument is only available with Authentication. Use purchase preview before making an actual purchase.

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

The website identifier string.

required
Payment Token (object) or Payment Instrument (object) or Payment Methods (object) or Payment Card (object) or Bank Account (object)

The payment instruction to be used for purchasing.

One of:

The payment instruction to be used for purchasing.

token
required
string

Payment Token ID.

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

The plan identifier string.

quantity
integer

Number of units of the product on the given plan.

object or null

The 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},.'&]+$

The 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 whether 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 whether 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},.#;:()']+$

The contact's job title.

object or null

The delivery 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},.'&]+$

The 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 whether 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 whether 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},.#;:()']+$

The contact's job title.

shippingRateId
string <= 50 characters

The shipping rate ID. If unset the cheapest applicable shipping rate is chosen.

couponIds
Array of strings

The list of coupons applied to the order.

password
string or null

If set would be used to create customer account.

redirectUrl
string or null <url>

The URL to redirect the end-user when an offsite transaction is completed. If website.url is https://example.com, then the redirectUrl could be set to any of these:

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

Defaults to the website's configured URL. You may use {id} or {result} as placeholders in the URL and we will replace them with the transaction's id and result accordingly.

Responses
201

Order was 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

The order identifier string.

object (StorefrontInvoice)

The initial invoice.

currency
required
string = 3 characters

Currency code in ISO 4217 format.

websiteId
required
string <= 50 characters

The website ID.

id
string <= 50 characters

The invoice ID.

invoiceNumber
integer

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

subscriptionId
string <= 50 characters

The related order's ID if available, otherwise null.

amount
number <double>

The invoice's amount.

amountDue
number <double>

The invoice's due amount.

subtotalAmount
number <double>

The invoice's subtotal amount.

discountAmount
number <double>

The invoice's discounts amount.

object (Shipping)

Shipping settings.

calculator
required
string

Shipping calculator.

amount
required
integer

Shipping amount.

object (InvoiceTax)

Invoice taxes.

calculator
required
string

Tax calculator.

required
Array of objects

Taxes applied to this invoice.

amount
integer

A sum of all invoice taxes.

object

Invoice's 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},.'&]+$

The 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},.#;:()']+$

The contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

object

Invoice's delivery 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},.'&]+$

The 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},.#;:()']+$

The 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 which will be displayed on the invoice.

notes
string

Notes for the customer which will be displayed on the invoice.

Array of objects (InvoiceItem)

Invoice items array.

Array
type
required
string

Invoice item's type.

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

Invoice item's price.

id
string <= 50 characters

The website identifier string.

description
string

Invoice item's description.

quantity
integer

Invoice item's quantity.

price
number <double>

Invoice item's total price.

productId
string <= 50 characters

The product's ID.

discountAmount
number <double>

Invoice item discount amount.

periodStartTime
string <date-time>

Start time.

periodEndTime
string <date-time>

End time.

periodNumber
integer

Invoice item subscription order period number.

createdTime
string <date-time>

Invoice item created time.

updatedTime
string <date-time> (UpdatedTime)

Read-only timestamp. This value updates when the resource is updated.

object

Invoice item tax.

Array of Self (object) or ProductLink (object) non-empty

Related resource links.

Array of ProductEmbed (object) or PlanEmbed (object) non-empty

Embedded objects that are requested by the expand query parameter.

Array of objects

Discounts applied.

Array
couponId
string <= 50 characters

Coupon's ID.

redemptionId
string <= 50 characters

Redemption ID.

amount
number <double>

Total amount that was discounted by this Coupon.

description
string

Discount description.

context
string (DiscountContext)
Default: "items"

The 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>

Invoice autopay scheduled time.

autopayRetryNumber
integer >= 0
Default: 0

Invoice autopay retry number.

status
string

Invoice status.

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

Delinquent collection period - difference between paidTime and dueTime in days.

collectionPeriod
integer

Collection period - difference between paidTime and issuedTime in days.

abandonedTime
string <date-time>

Invoice abandoned time.

voidedTime
string <date-time>

Invoice voided time.

paidTime
string <date-time>

Invoice paid time.

dueTime
string <date-time>

Invoice due time.

issuedTime
string <date-time>

Invoice issued time.

createdTime
string <date-time>

Invoice created time.

updatedTime
string <date-time>

Read-only timestamp. This value updates when the resource is updated.

paymentFormUrl
string <url>

URL where the customer can be redirected to pay for the invoice with one of the methods which are available for this customer. It's an alternative to creating a new transaction with empty methods.

Array of objects (StorefrontTransaction)

Invoice transactions array.

Array
id
string <= 50 characters

Unique transaction identifier string.

websiteId
string <= 50 characters

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

customerId
string <= 50 characters

Customer resource ID. Defaults to UUID v4.

type
string

Type of transaction.

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

Status of a transaction.

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

Result of a transaction.

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

Total amount of a 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 purchased amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string <= 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 whether 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 whether the transaction uses 3D Secure.

object

3D Secure object.

redirectUrl
string <uri>

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

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies whether a transaction is a retry.

billingDescriptor
string

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 whether the transaction has amount adjustment.

gatewayName
string

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" … 169 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 at which the transaction was processed.

createdTime
string <date-time>

Date and time at which the transaction was created.

updatedTime
string <date-time>

Date and time at which the transaction was last updated.

object (InstrumentReference)
approvalUrl
string <uri>

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

token
string

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

Array of Self (object) or ApprovalUrlLink (object) non-empty

Related resource links.

Array of Self (object) non-empty

Related resource links.

Array (non-empty)
Any of:
href
required
string

Link URL.

rel
required
string

Type of link.

Value: "self"
object (StorefrontTransaction)

The initial transaction.

id
string <= 50 characters

Unique transaction identifier string.

websiteId
string <= 50 characters

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

customerId
string <= 50 characters

Customer resource ID. Defaults to UUID v4.

type
string

Type of transaction.

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

Status of a transaction.

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

Result of a transaction.

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

Total amount of a 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 purchased amount may differ from the billing amount.

requestCurrency
string = 3 characters

Currency code in ISO 4217 format.

parentTransactionId
string <= 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 whether 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},.'&]+$

The 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},.#;:()']+$

The contact's job title.

hash
string <= 40 characters

Use this value to compare contacts for identical attribute values.

has3ds
boolean

Specifies whether the transaction uses 3D Secure.

object

3D Secure object.

server
string

Name of the 3D Secure server.

version
string

3D Secure version.

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

Specifies whether the cardholder is enrolled in 3D Secure.

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

3D Secure authentication response status.

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

3D Secure 2 authentication flow.

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

Specifies whether 3D Secure 2 was attempted but downgraded to 3D Secure 1.

redirectUrl
string <uri>

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

retryNumber
integer

Position of the transaction in the sequence of retries.

isRetry
boolean

Specifies whether a transaction is a retry.

billingDescriptor
string

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 whether the transaction has amount adjustment.

gatewayName
string

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" … 169 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 at which the transaction was processed.

createdTime
string <date-time>

Date and time at which the transaction was created.

updatedTime
string <date-time>

Date and time at which the transaction was last updated.

object (InstrumentReference)
method
required
string (PaymentMethod)

Payment method.

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

The payment instrument ID.

approvalUrl
string <uri>

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

token
string

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

Array of Self (object) or ApprovalUrlLink (object) non-empty

Related resource links.

Array (non-empty)
Any of:
href
required
string

Link URL.

rel
required
string

Type of link.

Value: "self"
token
string

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

401

Unauthorized access. Invalid credentials used.

403

Access forbidden.

422

Invalid data was sent.

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