Rebilly REST API

OpenAPI apis-guru paymentecommerce

Introduction

The Rebilly API is built on HTTP. Our API is RESTful. It has predictable resource URLs. It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body. You can use your favorite HTTP/REST library for your programming language to use Rebilly's API, or you can use one of our SDKs (currently available in and ).

We have other APIs that are also available. Every action from our is supported by an API which is documented and available for use so that you may automate any workflows necessary. This document contains the most commonly integrated resources.

Authentication

When you sign up for an account, you are given your first secret API key. You can generate additional API keys, and delete API keys (as you may need to rotate your keys in the future). You authenticate to the Rebilly API by providing your secret key in the request header.

Rebilly offers three forms of authentication: secret key, publishable key, JSON Web Tokens, and public signature key.

: used for requests made from the server side. Never share these keys. Keep them guarded and secure.
: used for requests from the client side. For now can only be used to create a and a .
: short lifetime tokens that can be assigned a specific expiration time.

Never share your secret keys. Keep them guarded and secure.

Errors

Rebilly follow's the error response format proposed in also known as Problem Details for HTTP APIs. As with our normal API responses, your client must be prepared to gracefully handle additional members of the response.

Forbidden

Conflict

NotFound

Unauthorized

ValidationError

SDKs

Rebilly offers a Javascript SDK and a PHP SDK to help interact with the API. However, no SDK is required to use the API.

Rebilly also offers , a client-side iFrame-based solution to help create payment tokens while minimizing PCI DSS compliance burdens and maximizing the customizability. is interacting with the .

Javascript SDK

Installation and usage instructions can be found . SDK code examples are included in these docs.

PHP SDK

For all PHP SDK examples provided in these docs you will need to configure the $client. You may do it like this:

Using filter with collections

Rebilly provides collections filtering. You can use ?filter param on collections to define which records should be shown in the response.

Here is filter format description:

Fields and values in filter are separated with :: ?filter=firstName:John.
Sub-fields are separated with .: ?filter=billingAddress.country:US.
Multiple filters are separated with ;: ?filter=firstName:John;lastName:Doe. They will be joined with AND logic. In this example: firstName:John AND lastName:Doe.
You can use multiple values using , as values separator: ?filter=firstName:John,Bob. Multiple values specified for a field will be joined with OR logic. In this example: firstName:John OR firstName:Bob.
To negate the filter use !: ?filter=firstName:!John. Note that you can negate multiple values like this: ?filter=firstName:!John,!Bob. This filter rule will exclude all Johns and Bobs from the response.
You can use range filters like this: ?filter=amount:1..10.
You can use gte (greater than or equals) filter like this: ?filter=amount:1.., or lte (less than or equals) than filter like this: ?filter=amount:..10. This also works for datetime-based fields.
You can create some and use them in filter: ?filter=firstName:@yourListName. You can also exclude list values: ?filter=firstName:!@yourListName.
Datetime-based fields accept values formatted using RFC 3339 like this: ?filter=createdTime:2021-02-14T13:30:00Z.

Expand to include embedded objects

Rebilly provides the ability to pre-load additional objects with a request.

You can use ?expand param on most requests to expand and include embedded objects within the _embedded property of the response.

The _embedded property contains an array of objects keyed by the expand parameter value(s).

You may expand multiple objects by passing them as comma-separated to the expand value like so:

And in the response, you would see:

Expand may be utilitized not only on GET requests but also on PATCH, POST, PUT requests too.

Getting started guide

Rebilly's API has over 300 operations. That's more than you'll need to implement your use cases. If you have a use case you would like to implement, please consult us for feedback on the best API operations for the task.

Our getting started guide will demonstrate a basic order form use case. It will allow us to highlight core resources in Rebilly that will be helpful for many other use cases too.

Within 25 minutes, you'll have sent API requests (via our console) to create a subscription order.

Homepage: https://api.apis.guru/v2/specs/rebilly.com/2.1.json
Provider: rebilly.com
OpenAPI version: 3.0.3
Spec (JSON): https://api.apis.guru/v2/specs/rebilly.com/2.1/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/rebilly.com/2.1/openapi.yaml

Tools (186)

Extracted live via the executor SDK.

3DSecure.get3DSecure

Retrieve a ThreeDSecure entry with specified identifier string.
3DSecure.get3DSecureCollection

Retrieve a list of ThreeDSecure entries
3DSecure.post3DSecure

Create a ThreeDSecure entry.
aml.getAmlEntry

Search multiple PEP/Sanctions/Adverse Media lists with first and last name to find any blocklisted identities. Performs a fuzzy search including soundex. Not all fields are guaranteed to be filled.
bankAccounts.getBankAccount

Retrieve a Bank Account with specified identifier string.
bankAccounts.getBankAccountCollection

Retrieve a list of Bank Accounts.
bankAccounts.patchBankAccount

Update bank account's values except for the account number and routing. number.
bankAccounts.postBankAccount

Create a Bank Account.
bankAccounts.postBankAccountDeactivation

Deactivate a Bank Account.
bankAccounts.putBankAccount

Create or update a BankAccount with predefined identifier string.
blocklists.deleteBlocklist

Delete a blocklist with predefined identifier string.
blocklists.getBlocklist

Retrieve a blocklist with specified identifier string.
blocklists.getBlocklistCollection

Retrieve a list of blocklists.
blocklists.postBlocklist

Create a blocklist.
blocklists.putBlocklist

Create a blocklist with predefined identifier string.
coupons.getCoupon

Retrieve a coupon with specified coupon ID string.
coupons.getCouponCollection

Retrieve a list of coupons.
coupons.getCouponRedemption

Retrieve a coupon redemption with specified identifier string
coupons.getCouponRedemptionCollection

Retrieve a list of coupon redemptions
coupons.postCoupon

Create a coupon.
coupons.postCouponExpiration

Set a coupon's expiry time with the specified coupon ID. The expiredTime of a coupon must be greater than its issuedTime. This cannot be performed on expired coupons.
coupons.postCouponRedemption

Redeem a coupon.
coupons.postCouponRedemptionCancellation

Cancel a coupon redemption
coupons.putCoupon

Create or update a coupon with predefined coupon ID.
customerAuthentication.deleteAuthenticationToken

Logout a customer.
customerAuthentication.deleteCredential

Delete a credential with predefined identifier string.
customerAuthentication.deletePasswordToken

Delete a Reset Password Token with predefined identifier string.
customerAuthentication.getAuthenticationOption

Read current authentication options.
customerAuthentication.getAuthenticationTokenCollection

Retrieve a list of auth tokens.
customerAuthentication.getAuthenticationTokenVerification

Verify an authentication token.
customerAuthentication.getCredential

Retrieve a credential with specified identifier string.
customerAuthentication.getCredentialCollection

Retrieve a list of credentials.
customerAuthentication.getPasswordToken

Retrieve a Reset Password Token with specified identifier string.
customerAuthentication.getPasswordTokenCollection

Retrieve a list of tokens.
customerAuthentication.postAuthenticationToken

Login a customer.
customerAuthentication.postAuthenticationTokenExchange

Exchange Authentication Token for JWT.
It will also invalidate an Authentication Token by default (so it can only be exchanged once).
customerAuthentication.postCredential

Create a credential.
customerAuthentication.postPasswordToken

Create a Reset Password Token.
customerAuthentication.putAuthenticationOption

Change options.
customerAuthentication.putCredential

Create or update a credential with predefined identifier string.
customers.deleteCustomer

Merge one duplicate customer to another target customer and delete the. former.
customers.deleteCustomerLeadSource

Delete a Lead Source that belongs to a certain customer.
customers.getCustomer

Retrieve a customer with specified identifier string.
customers.getCustomerCollection

Retrieve a list of customers.
customers.getCustomerLeadSource

Retrieve a Lead Source of given customer.
customers.postCustomer

Create a customer without a predefined ID. The customer's primary address will be used as the default address for payment instruments, subscriptions and invoices if none are provided.
If you wish to create the customer with a predefined ID (which we recommend to prevent duplication), you may use our PUT request described below.
Read our guide to to understand more.
customers.postCustomerTimelineCustomEventType

Create Customer Timeline custom event type.
customers.putCustomer

Create or update (upsert) a customer with predefined identifier string. Read our guide to to understand more.
customers.putCustomerLeadSource

Create a Lead Source for a customer.
customersTimeline.deleteCustomerTimeline

Delete a Customer Timeline message with predefined identifier string.
customersTimeline.getCustomerTimeline

Retrieve a customer message with specified identifier string.
customersTimeline.getCustomerTimelineCollection

Retrieve a list of customer timeline messages.
customersTimeline.getCustomerTimelineCustomEventType

Retrieve customer timeline custom event type.
customersTimeline.getCustomerTimelineCustomEventTypeCollection

Retrieve a list of customer timeline custom event types.
customersTimeline.getCustomerTimelineEventCollection

Retrieve a list of customer timeline messages for all customers.
customersTimeline.postCustomerTimeline

Create a customer Timeline comment or custom defined event.
customFields.getCustomField

Retrieve a schema of the given Custom Field for the given resource type.
customFields.getCustomFieldCollection

Retrieve a schema of Custom Fields for the given resource type.
customFields.putCustomField

Create or alter a schema of the given Custom Field for the given resource. type.
disputes.getDispute

Retrieve a dispute with specified identifier string.
disputes.getDisputeCollection

Retrieve a list of disputes.
disputes.postDispute

Create a dispute.
disputes.putDispute

Create or update a Dispute with predefined identifier string.
files.deleteAttachment

Delete the Attachment with predefined identifier string.
files.deleteFile

Delete the File with predefined identifier string.
files.getAttachment

Retrieve a Attachment with specified identifier string.
files.getAttachmentCollection

Retrieve a list of attachments. You may sort by the id, name, relatedId, relatedType, fileId, createdTime, and updatedTime.
files.getFile

Retrieve a File with specified identifier string.
files.getFileCollection

Retrieve a list of files.
files.getFileDownload

Download a file.
files.getFileDownloadExtension

Download image in specific format. Images are converted server-side.
files.postAttachment

Create an Attachment.
files.postFile
Additionally, a file can be sent with:.
- multipart/form-data POST request: in this case all property names are the same as the JSON ones (file is an uploaded file)
- file body request: the file body is sent as the request body, with the appropriate Content-Type. No additional properties can be set along the request data
The following file types only are allowed:
- jpg
- png
- gif
- pdf
- mp3
If using a Publishable Api Key, only private files can be created. The files can later on be modified or used using a secret API key.
files.putAttachment

Update the Attachment with predefined ID.
files.putFile

Update the File with predefined ID. Note that file can be uploaded with POST. only.
invoices.deleteInvoiceTimeline

Delete an Invoice Timeline message with predefined identifier string.
invoices.getCustomerUpcomingInvoiceCollection

Retrieve a list of upcoming invoices from the subscriptions which belong to. the given customer. The endpoint is temporary before upcoming invoices get a complete integration.
invoices.getInvoice

Retrieve an invoice with specified identifier string.
invoices.getInvoiceCollection

Retrieve a list of invoices.
invoices.getInvoiceItemCollection

Retrieve an invoice items with specified invoice identifier string.
invoices.getInvoiceTimeline

Retrieve a invoice message with specified identifier string.
invoices.getInvoiceTimelineCollection

Retrieve a list of invoice timeline messages.
invoices.getInvoiceTransactionAllocationCollection

Get the precise amounts from a transaction allocated as invoice payments.
invoices.postInvoice

Create an invoice.
invoices.postInvoiceAbandonment

Abandon an invoice with specified identifier string.
invoices.postInvoiceIssuance

Issue an invoice with specified identifier string. It must be in draft status.
invoices.postInvoiceItem

Create an invoice item.
invoices.postInvoiceRecalculation

Recalculate an invoice with specified identifier string. It will recalculate shipping rates, taxes, discounts. It is useful when coupon was revoked or customer redeemed coupon after invoice was issued and you want to apply it to this invoice.
invoices.postInvoiceReissuance

Reissue an invoice with specified identifier string. It must be issued. (status must be unpaid or past-due).
invoices.postInvoiceTimeline

Create an invoice Timeline comment.
invoices.postInvoiceTransaction

Apply a transaction to an invoice. The invoice must be unpaid. The transaction must have a non-zero unused amount (not fully applied to other invoices).
invoices.postInvoiceVoid

Void an invoice with specified identifier string.
invoices.putInvoice

Create or update an invoice with predefined identifier string.
kycDocuments.deleteKycRequest

Delete the KYC request with the predefined identifier string.
kycDocuments.getKycDocument

Retrieve a KYC document with specified identifier string.
kycDocuments.getKycDocumentCollection

Retrieve a list of KYC documents.
kycDocuments.getKycRequest

Retrieve a KYC request with specified identifier string.
kycDocuments.getKycRequestCollection

Retrieve a list of KYC requests.
kycDocuments.patchKycRequest

Update a KYC request.
kycDocuments.postKycDocument

Create a KYC Document.
kycDocuments.postKycDocumentAcceptance

Marks that status of the document as accepted. Updates the review time and reviewer information. Intended to be used for manual overrides.
kycDocuments.postKycDocumentMatches

Updates a KYC document's documentMatches. Intended to be used for manual overrides.
kycDocuments.postKycDocumentRejection

Marks that status of the document as rejected. Updates the review time and reviewer information. Intended to be used for manual overrides.
kycDocuments.postKycDocumentReview

Mark the KYC document as reviewed. Updates the review time and reviewer. information.
kycDocuments.postKycRequest

Create a KYC Request.
kycDocuments.putKycDocument

Create or update a KYC document with predefined identifier string.
orders.deleteSubscriptionCancellation

Delete an order's cancellation. Only draft can be deleted.
orders.deleteSubscriptionTimeline

Delete an Order Timeline message with predefined identifier string.
orders.getSubscription

Retrieve an order with specified identifier string.
orders.getSubscriptionCancellation

Retrieve an order сancellation with specified identifier string.
orders.getSubscriptionCancellationCollection

Retrieve a list of cancellations for all subscriptions.
orders.getSubscriptionCollection

Retrieve a list of orders.
orders.getSubscriptionReactivation

Retrieve an order reactivation with specified identifier string.
orders.getSubscriptionReactivationCollection

Retrieve a list of reactivations for all subscriptions.
orders.getSubscriptionTimeline

Retrieve a order message with specified identifier string.
orders.getSubscriptionTimelineCollection

Retrieve a list of order timeline messages.
orders.getSubscriptionUpcomingInvoiceCollection

Retrieve an upcoming invoice from the specified subscription order. The endpoint is temporary before upcoming invoices get a complete integration.
orders.postSubscription

Create an order. Consider using the upsert. operation to accomplish this task.
orders.postSubscriptionCancellation

Cancel an order or preview the cancellation parameters before that.
orders.postSubscriptionInterimInvoice

Issue an interim invoice for a subscription, typically used in conjunction. with plan changes and pro rata adjustments. This process creates an invoice, adds the subscription's line items to the invoice, and issues the invoice, and applies payment to it if a transaction id is supplied.
orders.postSubscriptionItemsChange

Change an order's items or quantities and designate when and if there should be pro-rata credits given.
orders.postSubscriptionReactivation

Reactivate a subscription.
orders.postSubscriptionTimeline

Create an order Timeline comment.
orders.postUpcomingInvoiceIssuance

Issue an upcoming invoice with specified identifier string for early pay.
orders.putSubscription

Create or update an order with predefined identifier string.
orders.putSubscriptionCancellation

Cancel a subscription.
paymentCards.getPaymentCard

Retrieve a Payment Card with specified identifier string.
paymentCards.getPaymentCardCollection

Retrieve a list of Payments Cards.
paymentCards.patchPaymentCard

Update any of the payment card's values except for the pan.
paymentCards.postPaymentCard

Create a Payment Card.
paymentCards.postPaymentCardDeactivation

Deactivate a Payment Card.
paymentCards.putPaymentCard

Create a payment card with predefined ID
paymentInstruments.getPaymentInstrument

Retrieve a payment instrument by ID.
paymentInstruments.getPaymentInstrumentCollection

Retrieve a list of payment instruments.
paymentInstruments.patchPaymentInstrument

Update allowed payment instrument's values.
paymentInstruments.postPaymentInstrument

Create a payment instrument. If such payment card or bank account payment instrument already exists then updates it instead.
paymentInstruments.postPaymentInstrumentDeactivation

Deactivate a payment instrument.
paymentTokens.getToken

Retrieve a token with specified identifier string.
paymentTokens.getTokenCollection

Retrieve a list of tokens.
paymentTokens.postDigitalWalletValidation

is the recommended way to use when validating a digital wallet session.
paymentTokens.postToken

is the recommended way to create a payment token because it minimizes PCI DSS compliance. Once a payment token is created, it can only be used once.
A payment token expires upon first use or within 30 minutes of the token creation (whichever comes first).
payPalAccounts.getPayPalAccount

Retrieve a PayPal Account with specified identifier string.
payPalAccounts.getPayPalAccountCollection

Retrieve a list of PayPal Accounts.
payPalAccounts.postPayPalAccount

Create a PayPal Account.
payPalAccounts.postPayPalAccountDeactivation

Deactivate a PayPal Account.
payPalAccounts.putPayPalAccount

Create a PayPal account with predefined ID
plans.deletePlan

Delete a Plan with predefined identifier string.
plans.getPlan

Retrieve a plan with specified identifier string.
plans.getPlanCollection

Retrieve a list of plans.
plans.postPlan

Create a plan.
plans.putPlan

Create or update a Plan with predefined identifier string.
products.deleteProduct

Delete a product with predefined identifier string.
products.getProduct

Retrieve a product with specified identifier string.
products.getProductCollection

Retrieve a list of products.
products.postProduct

Create a Product.
products.putProduct

Create a product with predefined identifier string.
search.getSearch

Search merchant's data to return resources such as customers, invoices, orders, transactions.
shippingZones.deleteShippingZone

Delete a shipping zone with predefined identifier string.
shippingZones.getShippingZone

Retrieve a shipping zone with specified identifier string.
shippingZones.getShippingZoneCollection

Retrieve a list of shipping zones.
shippingZones.postShippingZone

Create a Shipping Zone.
shippingZones.putShippingZone

Create a shipping zone with predefined identifier string.
tags.deleteTag

Delete a tag. It's an asynchronous operation.
tags.deleteTagCustomer

Untag a customer.
tags.deleteTagCustomerCollection

Untag a list of customers. If the customer from the list is already untagged it will be ignored. It's an asynchronous operation.
tags.getTag

Retrieve a tag.
tags.getTagCollection

Retrieve a list of tags.
tags.patchTag

Update a tag.
tags.postTag

Create a tag.
tags.postTagCustomer

Tag a customer.
tags.postTagCustomerCollection

Tag a list of customers. If the customer from the list is already tagged it will be ignored. It's an asynchronous operation.
transactions.deleteTransactionTimeline

Delete a Transaction Timeline message with predefined identifier string.
transactions.getTransaction

Retrieve a Transaction with specified identifier string.
transactions.getTransactionCollection

Retrieve a list of transactions.
transactions.getTransactionTimeline

Retrieve a timeline message with specified identifier string.
transactions.getTransactionTimelineCollection

Retrieve a list of transaction timeline messages.
transactions.patchTransaction

Update a transaction's custom fields.
transactions.postPayout

Create a transaction of type credit.
transactions.postReadyToPay

Get available payment methods for a specific transaction or a purchase.
The payment methods order shown to a customer SHOULD be the same as the order in the response.
The list of available methods is generated from available intersected with the last matched adjust-ready-to-pay action on ready-to-pay-requested event.
If there were no actions matched for the specific request – all methods supported by the Gateway Accounts are sent.
To invert this behavior – place an all-matching rule at the very end of the ready-to-pay-requested event in Rules Engine with an empty paymentMethods property of the adjust-ready-to-pay action.
transactions.postTransaction
Create a transaction of type sale or authorize. This endpoint supports two main styles of transactions:
1. A real-time decision and response.
2. User approval/interaction is required.
A real-time decision is very familiar. You send a request, and inspect the result of the response for approved or declined.
However, many transactions, especially those for alternative methods, require the user to interact with a 3rd party. You may be able to envision PayPal, for example, the user must give permission to complete the payment (or accept the billing agreement).
Even payment cards may require user approval in the case of 3D secure authentication. In the event that approval is required, you will receive a response back and notice that the result is unknown. You will find that the status is waiting-approval. And you will find in the _links section of the response a link for the approvalUrl.
In this case you would either open the approvalUrl in an iframe or in a pop (better workflow for mobile).
transactions.postTransactionQuery

Query a Transaction with a specified identifier string. The query will contact the gateway account to find the result and amount/currency. The response should be analyzed. If deemed appropriate, the transaction could be updated using the Transaction Update API.
transactions.postTransactionRefund

Refund a Transaction with specified identifier string. Note that the refund will be in the same currency as the original transaction.
transactions.postTransactionTimeline

Create a transaction Timeline comment.
transactions.postTransactionUpdate

Update a Transaction manually to completed status with given result with optional currency and amount.
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools