# please make use of the swagger docs: https://swagger.io/specification/
#
# this doc has many refactor opportunities. as you add/modify
# for your own features, feel free to use existing schemas and/or
# define new ones, fixup examples, add examples, etc. basically
# take any refactor opportunities you can, keeping in mind
# that shareable are in the `components` section. also, please
# respect any existing alphabetizing as it makes it easier to
# find what you're looking for. =]
#
# can up date to 3.1.0 once swagger implements it properly:
# https://github.com/swagger-api/swagger-parser/issues/1535
openapi: 3.0.3
info:
title: Recurly V2 API
description: "# Getting Started
Welcome to the reference documentation for Recurly's XML API v2. Here
you will find a complete
reference for all API v2 operations.
If you're building a new product, or just getting started with Recurly,
we recommend
using our newer [JSON API v3](/developers/api/latest).
Now let's get started with API v2.
# Authentication
##### API Authentication (HTTP Basic)
Recurly uses HTTP Basic Authentication—your [Private API
key](https://app.recurly.com/go/developer/api_access) is securely encrypted
by the SSL channel.
If you are testing the API calls via the command line with cURL, try:
```
curl -H 'Accept: application/xml' \\
\ -H 'X-Api-Version: 2.29' \\
\ -H 'Content-Type: application/xml; charset=utf-8' \\
\ -u '[apikey]' \\
\ https://[subdomain].recurly.com/v2/accounts
```
Replace `[apikey]` and `[subdomain]` with the appropriate values for
your site.
##### Calculating your own authorization header
Most programming languages encode the authorization header
automatically. With HTTP Basic Authentication, the `Authorization` header is
a string containing a Base-64 encoded username and password. In the case of
Recurly's API, you need only specify the username as your API key. If your
library requires a password, set it to an empty string.
```
\"Authorization\": \"Basic \" + base64_encode(API Key)
```
##### Additional Request Headers
**Accept Header**
Recurly API v2 returns results as XML. Your requests should always
include the header requesting the results as XML:
```
Accept: application/xml
```
**Content-Type Header**
When sending data to Recurly in a POST or PUT request, your request must
specify the content type of your request:
```
Content-Type: application/xml; charset=utf-8
```
**X-Api-Version Header**
When sending data to Recurly, your request should specify the API
version you're attempting to interact with:
```
X-Api-Version: 2.29
```
You learn more about the different versions in the [API
Versioning](doc:versioning) section.
##### Public API Key
Recurly uses two types of API keys: public and private. The Public API
key is used by [Recurly.js](doc:recurlyjs) to identify its requests as
belonging to your Recurly site. This key can be safely included in
Javascript code.
Recurly provides each site with one Public Key. The Public API Key can
be regenerated on the [API
Credentials](https://app.recurly.com/go/developer/api_access) page.
##### Private API Keys
###### Treat your Private API Keys like passwords!
The API key allows access to your site's data. Do not include it in
Javascript code exposed to browsers.
\ \
Recurly supports the use of multiple Private API keys, which can be used
to integrate third party services using unique, controlled credentials.
**Limits & Pricing**
Merchants on the Starter or grandfathered Recurly plans or merchants in
sandbox mode will be granted 5 private API keys. Merchants on Recurly's
Professional plan will be granted 10 private API keys.
**Default Key**
Your default private API key should be used to integrate Recurly with
your backend systems. There will be at least one key active at all times.
**Additional Keys**
Additional private API keys should be used to connect your Recurly data
to additional sources, like analytics software, accounting packages, or
email tools. Recurly recommends clearly labeling the name of each key to
identify the associated vendor.
**Regenerating Private API Keys**
Your API key can be regenerated by clicking on the Regenerate button on
the [API credentials](https://app.recurly.com/go/developer/api_access) page.
When you generate a private API key, you have two options:
1. Block the old key immediately. This is primarily recommended when the
security of a key has been compromised.
2. Allow the old key access for 12 hours. This is primarily used when
updating systems and a smooth transition between keys is needed.
*If a private API key is changed, an email alert will be sent to your
Recurly Site Technical Contact.*
**Read-Only Keys**
When creating a private key, you will have the option to set the key to
“read-only”. This means the API key may make GET requests but cannot not
PUT, POST or DELETE requests.
\ \
# API Versioning
Recurly strives to provide developers with stable APIs to integrate
against while still being able to provide new and expanded functionality. To
balance these two goals we provide different API versions and only add new
features to the latest version of the API. This allows you to choose the
best time to update your integration and take advantage of new features.
Recurly offers the following API
versions: [2.29](https://recurly.com/developers/api-v2/v2.29),
[2.28](https://recurly.com/developers/api-v2/v2.28),
[2.27](https://recurly.com/developers/api-v2/v2.27),
[2.26](https://recurly.com/developers/api-v2/v2.26),
[2.25](https://recurly.com/developers/api-v2/v2.25),
[2.24](https://recurly.com/developers/api-v2/v2.24),
[2.22](https://recurly.com/developers/api-v2/v2.22),
[2.21](https://recurly.com/developers/api-v2/v2.21),
[2.20](https://recurly.com/developers/api-v2/v2.20),
[2.19](https://recurly.com/developers/api-v2/v2.19),
[2.18](https://recurly.com/developers/api-v2/v2.18),
[2.17](https://recurly.com/developers/api-v2/v2.17),
[2.16](https://recurly.com/developers/api-v2/v2.16),
[2.15](https://recurly.com/developers/api-v2/v2.15),
[2.14](https://recurly.com/developers/api-v2/v2.14),
[2.13](https://recurly.com/developers/api-v2/v2.13),
[2.12](https://recurly.com/developers/api-v2/v2.12),\
[2.11](https://recurly.com/developers/api-v2/v2.11),
[2.10](https://recurly.com/developers/api-v2/v2.10),
[2.9](https://recurly.com/developers/api-v2/v2.9),
[2.8](https://recurly.com/developers/api-v2/v2.8), [2.7](https://developer\
s.recurly.com/api-v2/v2.7),
[2.6](https://recurly.com/developers/api-v2/v2.6),
[2.5](https://recurly.com/developers/api-v2/v2.5),
[2.4](https://recurly.com/developers/api-v2/v2.4),
[2.3](https://recurly.com/developers/api-v2/v2.3),
[2.2](https://recurly.com/developers/api-v2/v2.2).
**Requesting A Version**
###### API Version Sunset
As a matter of policy, Recurly sunsets API versions two years after the
date that the subsequent version is released (rounded to the nearest month).
Sunset means that Recurly will no longer support, provide bug fixes, or
patch security issues for a given API version.
See
https://recurly.com/developers/pages/api-v2/support-policy-and-roadmap.html
for a detailed sunset schedule.
We will be happy to assist you in upgrading to the current API version.
Please reach out to us at support@recurly.com if you have any questions with
this documentation.
\ \
When making requests to Recurly, your request should specify the desired
API version using the `X-Api-Version` header:
```
X-Api-Version: 2.29
```
For backwards compatibility, if no version is specified the default is
2.0.
**Deprecation**
To signal that an API version is deprecated and will be removed in the
future, Recurly will respond the following headers:
```
Recurly-Deprecated: TRUE
Recurly-Sunset-Date: 2018-06-01T00:00:00+00:00
```
The sunset date is an ISO 8601 date time when the version will no longer
be accessible.
Your integration should check for those headers so you can make updates
in a timely fashion.
**Changes in v2.29**
Request and Response changes:
\ - Added `GET v2/external_product_references/{uuid}`
\ - Gets an external product reference details
\ - Percentage tiered pricing changes:
\ - Changed `POST v2/subscriptions` response:
\ - Added `` array
\ - Changed `POST v2/subscriptions/preview` response:
\ - Added `` array
\ - Changed `POST v2/purchases` response:
\ - Added `` array
\ - Changed `POST v2/purchases/preview` response:
\ - Added `` array
\ - Changed `POST v2/subscriptions/{uuid}/preview` response:
\ - Added `` array
\ - Changed `GET v2/subscriptions/{subscription_uuid}/add_ons/{add_on_code}/usage/{usage_id}` response:
\ - Added `` array
\ - Invoice response format has changed:
\ - Added . Field is present if taxes are enabled. Value is `true` or `false` based on a successful response from the tax service.
\ - Added support for Applying Credit Balance to an existing collectible charge invoice
\ - Changed `GET v2/accounts/{account_code}/balance`
\ - Added on response
\ - Added `PUT v2/invoices/{invoice_number}/apply_credit_balance`
\ - Applies an account's credit balance to a collectible charge invoice
\ - Added support for Custom Field Definition
\ - Added new endpoint `GET custom_field_definitions`
\ - Added new endpoint `GET custom_field_definitions/{custom_field_definition_id}`
\ - Added support for Custom Fields on Plans, Items, Accounts and Subscriptions
\ - Changed `GET plans`
\ - Added on response
\ - Changed `POST plans`
\ - Added on response
\ - Added on request to save/delete custom fields on plans
\ - Changed `GET plans/{plan_code}`
\ - Added on response
\ - Changed `PUT plans/{plan_code}`
\ - Added on response
\ - Added on request to save/delete custom fields on plans
\ - Changed `GET items`
\ - Added on response
\ - Changed `POST items`
\ - Added on response
\ - Added on request to save/delete custom fields on items
\ - Changed `GET items/{item_code}`
\ - Added on response
\ - Changed `PUT items/{item_code}`
\ - Added on response
\ - Added on request to save/delete custom fields on items
\ - Changed `PUT items/{item_code}/reactivate`
\ - Added on response
\ - Changed `GET subscriptions`
\ - Added on response
\ - Changed `POST subscriptions`
\ - Added on response
\ - Added on request to save/delete custom fields on subscriptions
\ - Changed `GET subscriptions/{uuid}`
\ - Added on response
\ - Changed `PUT subscriptions/{uuid}`
\ - Added on response
\ - Added on request to save/delete custom fields on subscriptions
\ - Changed `GET accounts`
\ - Added on response
\ - Added `` on response
\ - Changed `POST accounts`
\ - Added on response
\ - Added on request to save/delete custom fields on accounts
\ - Added `` on the request and response
\ - Changed `GET accounts/{account_code}`
\ - Added on response
\ - Added `` on response
\ - Changed `PUT accounts/{account_code}`
\ - Added on response
\ - Added on request to save/delete custom fields on accounts
\ - Added `` on the request and response
\ - Dunning Campaigns feature changes:
\ - Added `GET v2/dunning_campaigns`
\ - Returns all active dunning campaigns for a site
\ - Added `GET v2/dunning_campaigns/{id}`
\ - Returns the specified dunning campaign for a site
\ - Added `PUT v2/dunning_campaigns/{id}/bulk_update`
\ - Given plan codes, updates specified plans with the dunning campaign
\ - Changed `POST v2/plans` and `PUT v2/plans/{plan_code}` requests:
\ - Added optional `` field
\ - Changed `GET v2/plans/{plan_code}`, `POST v2/plans`, and `PUT v2/plans/{plan_code}` responses:
\ - Added `` field
\ - Changed `POST v2/accounts` and `PUT v2/accounts/{account_code}` requests:
\ - Added optional `` field
\ - Changed Account object response:
\ - Added ``
\ - Changed Invoice object response:
\ - Added ``
\ - Changed `POST v2/purchases`, `POST /v2/purchases/preview` and `POST v2/purchases/authorize` requests:
\ - Added `` field
\ - Changed `POST v2/subscriptions` and `POST v2/subscriptions/preview` requests:
\ - Added `` field
\ - Changed `POST v2/coupons` request:
\ - Added optional ``boolean and `` array fields
\ - Changed `POST v2/coupons` response:
\ - Added `` boolean and `` array fields
\ - Changed `GET v2/coupons` response:
\ - Same changes as `POST v2/coupons` response
\ - Changed `GET v2/coupons/{coupon_code}` response:
\ - Same changes as `POST v2/coupons` response
\ - Changed `PUT v2/coupons/{coupon_code}` response:
\ - Same changes as `POST v2/coupons` response
\ - Changed `PUT v2/coupons/{coupon_code}/restore` response:
\ - Same changes as `POST v2/coupons` response
\ - Changed `PUT v2/coupons/{coupon_code}/unique_coupon_codes` response:
\ - Same changes as `POST v2/coupons` response
\ - Changed `GET v2/plans/{plan_code}/add_ons/{add_on_code}` response:
\ - description: includes tiers for usage percentage type add ons, and usage percentage value within the tiers if configured
\ - Changed `POST v2/plans/{plan_code}/add_ons` request:
\ - description: Added support for usage percentage tiers
\ - Changed `PUT v2/plans/{plan_code}/add_ons/{add_on_code}` request:
\ - description: Added support for usage percentage tiers
\ - Wallet feature changes with the `wallet` feature flag enabled on the site:
\ - descriptions:
\ - The `primary_payment_method` field is used to designate the primary billing info on the account.
\ - The `billing_info_uuid` is the value that represents a specific billing info for an end customer.
\ - The `backup_payment_method` field is used to designate the backup billing info on the account
\ - The `backup_payment_method_used` field is used to indicate whether this transaction was fulfilled through a backup payment method.
\ - Added `POST v2/accounts/{account_id}/billing_infos`
\ - Creates a billing info for an account.
\ - Added index route `GET v2/accounts/{account_code}/billing_infos`
\ - Returns all the active billing infos for an account.
\ - Added `GET v2/accounts/{account_code}/billing_infos/{billing_info_uuid}`
\ - Returns the specified billing info for an account.
\ - Added `PUT /v2/accounts/{account_code}/billing_infos/{billing_info_uuid}`
\ - Updates an existing active billing info.
\ - Added `DELETE /v2/accounts/{account_code}/billing_infos/{billing_info_uuid}`
\ - Deactivates an existing active billing info.
\ - Changed `GET v2/accounts/{account_id}/billing_info` response:
\ - Added `` boolean field
\ - Changed `POST v2/purchases`:
\ - Added optional `` boolean field
\ - path: ``
\ - Changed `PUT v2/purchases/preview`:
\ - Added optional `` boolean field
\ - path: ``
\ - Added optional `` field
\ - Changed `POST v2/subscriptions`
\ - Added optional `` field
\ - Added optional `` boolean field
\ - path: ``
\ - Changed `POST v2/subscriptions/preview`
\ - Added optional `` field
\ - Added optional `` boolean field
\ - path: ``
\ - Changed `PUT v2/subscriptions/{subscription_uuid}`
\ - Added optional `` field
\ - Changed `POST v2/subscriptions/{subscription_uuid}/preview`
\ - Added optional `` field
\ - Changed `GET, POST v2/accounts/{account_id}/billing_infos`
\ - Added `` boolean field
\ - Changed `GET, POST, PUT, DELETE v2/accounts/{account_code}/billing_infos/{billing_info_uuid}`
\ - Added `` boolean field
\ - Changed `GET, POST, PUT v2/accounts/{account_id}/billing_info`
\ - Added `` boolean field
\ - Changed `GET, POST v2/subscriptions` and `v2/subscriptions/preview`
\ - Added optional `` boolean field
\ - path: ``
\ - Changed `POST v2/purchases` and `v2/purchases/preview`:
\ - Added optional `` boolean field
\ - path: ``
\ - Changed `GET v2/transactions/{transaction_uuid}`
\ - Added `` boolean field
\ - Invoice Customization feature changes for sites on Pro or Elite plans:
\ - Changed `GET v2/accounts` response:
\ - Added `` field
\ - Changed `GET v2/accounts/{account_code}` response:
\ - Added `` field
\ - Changed `POST v2/accounts` request:
\ - Added `` field
\ - Changed `PUT v2/accounts/{account_code}` request:
\ - Added `` field
\ - Added new endpoints:
\ - `GET v2/invoice_templates/{invoice_template_uuid}/accounts`
\ - `GET v2/invoice_templates`
\ - `GET v2/invoice_templates/{invoice_template_uuid}`
\ - Decimal Quantity feature changes with the `Decimal Quantity` feature enabled:
\ - Changed `GET v2/invoices` response:
\ - Added `` field to line items
\ - Added `` field to line items
\ - Changed `GET v2/invoices/{invoice_number} response:`
\ - Added `` field to line items
\ - Added `` field to line items
\ - Changed `POST /v2/subscriptions/:subscription_uuid/add_ons/:add_on_code/usage` request:
\ - Allow up to nine decimal places for `amount` field
\ - Added `` field
\ - Changed `POST /v2/invoices/{invoice_number}/refund` request:
\ - Added `` field to line items
\ - Added support for last-in-period usage billing:
\ - Changed `POST v2/plans/{plan_id}/add_ons` request and response:
\ - Added `` field
\ - Changed `GET v2/plans/{plan_id}/add_ons` response:
\ - Same changes as `POST v2/plans/{plan_id}/add_ons` response.
\ - Changed `GET v2/plans/{plan_id}/add_ons/{add_on_id}` response:
\ - Same changes as `POST v2/plans/{plan_id}/add_ons` response.
\ - Changed `PUT v2/plans/{plan_id}/add_ons/{add_on_id}` request and response:
\ - Same changes as `POST v2/plans/{plan_id}/add_ons` request.
\ - Changed `POST v2/subscriptions` response:
\ - Added the following to ``:
\ - Added `` field
\ - Changed `POST v2/subscriptions/preview` response:
\ - Same changes as `POST v2/subscriptions` response
\ - Changed `PUT v2/subscriptions/{subscription_uuid}` response:
\ - Same changes as `POST v2/subscriptions` response
\ - Changed `PUT v2/subscriptions/{subscription_uuid}/preview` response:
\ - Same changes as `POST v2/subscriptions` response
\ - Changed `GET v2/subscriptions/{subscription_uuid}` response:
\ - Same changes as `GET v2/subscriptions` response
\ \
# API Support Policy and Roadmap
[API Support Policy and
Roadmap](https://recurly.com/developers/pages/api-v2/support-policy-and-roa\
dmap.html)
\ \
# Pagination
##### Next Link
The amount of records returned within a single API request defaults to
50. It may be changed to a maximum of 200 using a `per_page` query
parameter, e.g. to return 200 accounts at a time:
```
https://your-subdomain.recurly.com/v2/accounts?per_page=200
```
When there are more records remaining than fit in the current response,
the `Link` header is specified with the URI to the next page of results.
```
Status: 200 OK\
Link:
; rel=\"next\"\
ETag: \"a4b0568a2278bc591ceb64b31547eb78\"\
```
The `cursor` parameter is a time-based pointer indicating where to
resume the results. By using a cursor instead of page numbers, the API
avoids returning duplicate records in the case where additional resources
are added between pagination requests.
##### Sorting and Filtering
\ Many endpoints support these advanced pagination parameters:
* `sort` : String: The attribute that will be used to order records:
`created_at`, `updated_at`. Defaults to `created_at`.
* `order` : String : The order in which products will be returned: `asc`
for ascending order, `desc` for descending order. Defaults to `desc`.
* `begin_time` : Datetime : Operates on the attribute specified by the
sort parameter. Filters records to only include those with datetimes greater
than or equal to the supplied datetime. Accepts an ISO 8601 date or date and
time.
* `end_time` : Datetime : Operates on the attribute specified by the
sort parameter. Filters records to only include those with datetimes less
than or equal to the supplied datetime. Accepts an ISO 8601 date or date and
time.
Review the parameters on each endpoint for more details.
###### Updated at really means last updated at
An account that was updated on `2016-01-19` and then again on
`2016-03-23` would not be returned in a request for
`sort=updated_at&end_time=2016-03-01`.
\ \
##### Counting Records
Starting with API version 2.6, you must explicitly make a `HEAD` request
to get the server count. Endpoints that return a list of resources will
respond to this request and include a header indicating the total number of
records available. They will not contain the xml body. The server count is
specified with the `X-Records` header. E.g., for an endpoint with 14
records:
```
X-Records: 14
```
You can pass filtering parameters (described above) to narrow down the
resources you wish to count. Consider the example of counting all
`collected` invoices in `2016`. You can send a `HEAD` request to this
endpoint then parse the count from the X-Records response header:
```
https://your-subdomain.recurly.com/v2/invoices?begin_time=2016-01-01T00\
:00:00&end_time=2017-01-01T00:00:00&state=collected
```
##### Examples
This will return accounts that were created on or before 2016-01-01 0:00
UTC in descending order of creation date:
```
https://your-subdomain.recurly.com/v2/accounts?sort=created_at&order=de\
sc&end_time=2016-01-01
```
This will return accounts that were last updated on or after 2016-07-01
10:30:01 Mountain Daylight Time in ascending order of updated date:
```
https://your-subdomain.recurly.com/v2/accounts?sort=updated_at&order=as\
c&begin_time=2016-07-01T10:30:01-06:00
```
###### Beware of changes to records when sorting by updated_at
It's important to be aware that when paging through records sorted by
their `updated_at` value, the order will change if they are modified:
* In ascending order, changes to records in previous pages will cause
them to move back the end of the list, meaning you may see them multiple
times. This can be avoided by using the time the pagination starts as the
`end_time`.
* In descending order, changes to records in later pages will cause them
to move up to the beginning of the list, meaning you would miss results.
\ \
PHP
Ruby
Python
Dotnet
```php
Invoices
$account = Recurly_Account::get('my_account_code');
// Calling ->invoices returns a Stub which allows lazily loading the
list
$invoices = $account->invoices;
print $invoices;
// =>
/**
\ * Prior to 2.5.0 calling ->get() would only return the first page
\ * of results. With 2.5.0 and later, all results will be returned.
\ */
foreach ($invoices->get() as $inv) {
\ print $inv->invoice_number . \"\\n\";
}
/**
\ * Creating a List object directly will also allow you to iterate
\ * through all pages
\ */
$invoices = Recurly_InvoiceList::getForAccount('my_account_code');
// Prints all invoices on the account
foreach ($invoices as $inv) {
\ print $inv->invoice_number . \"\\n\";
}
```
```ruby
# Pagination in the ruby client is done using
# the Recurly::Pager class.
# You can also create a Pager directly from any resource
Recurly::Invoice.paginate.class
#=> Recurly::Resource::Pager
# paginate optionally takes the sorting and filtering params
# if you want to specify them
opts = {
\ begin_time: DateTime.new(2016,1,1),
\ end_time: DateTime.new(2017,1,1),
\ state: :collected,
\ per_page: 10
}
# find_each will fetch the pages for you
# until there are none left. It presents
# all the invoices on the server as a single enumerable
Recurly::Invoice.paginate(opts).find_each do |invoice|
\ puts invoice.invoice_number
end
# You can also use #find_each directly on the resource
Recurly::Invoice.find_each do |invoice|
\ puts invoice.invoice_number
end
# When accessing a sub resource with a many-to-one relation\
# to the parent model, the attribute returns a
Recurly::Resource::Pager.\
# For example, take Account -> Invoices
account = Recurly::Account.find('my_account_code')
account.invoices.class
#=> Recurly::Resource::Pager
# Pager#each can be used to iterate through the only the given page
account.invoices.each do |invoice|
\ puts invoice.invoice_number
end
# The default page size is 50 items, if you wish to page through more
# you can use Pager#find_each, find_each continues to fetch pages until
# there are none left
account.invoices.find_each do |invoice|
\ puts invoice.invoice_number
end
```
```python
# When accessing a sub resource with a many-to-one relation
# to the parent model, the attribute returns a `relatiator` function.
# When called it returns a recurly.resource.Page.
# For example, take Account -> Invoices
account = recurly.Account.get('tester')
print account.invoices
# =>
print account.invoices().__class__
# =>
# To page through every invoice on the account
for invoice in account.invoices():
\ print invoice.invoice_number
# You can also call the all() method on
# a resource to page through every resource
# on your site. For instance, to page through
# every invoice:
for invoice in recurly.Invoice.all():
\ print invoice.invoice_number
```
```csharp
using System.Linq;
var accounts = Accounts.List();
while (accounts.Any())
{
\ foreach (var account in accounts)
\ Console.WriteLine(account);
\ accounts = accounts.Next;
}
```
\
###### PHP Pagination
The PHP `Recurly_Pager` class sets up an iterator across all the
relevant records. It does not provide pagination functionality by default.
\ \
\ \
# Rate Limits
In order to provide a fast response time to all our customers, we may
rate limit excessive requests. By default, new Recurly sites have the
following API rate limits:
* Sandbox sites: 400 requests/min. All requests count towards the rate
limit.
* Production sites: 1,000 requests/min. Only GET and HEAD requests count
towards the rate limit.
Once your site moves into production mode, Recurly will only rate limit
GET and HEAD requests. New subscriptions, account modifications, and other
requests using POST, PUT, or DELETE methods will not count against your rate
limit.
The rate limit is calculated over a sliding 5 minute window. This means
a production site could make 4,000 requests within one minute and not hit
the rate limit so long as the site made less than 1,000 requests during the
prior 4 minutes.
When your site reaches its rate limit, your site technical contact will
receive an email alerting them of the issue. This email will be sent not
more than once every three hours. Our support team will also be notified.
Please reach out to Recurly support if you need assistance in resolving this
issue.
If an API request exceeds the rate limit, the API returns a 429 status
code indicating `Too Many Requests`. If your business needs a higher limit,
please contact support.
##### HTTP Headers
Every authenticated API request returns headers with your current rate
limit information. Your requests' rate limit headers may look like:
```
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1414622019
```
The `X-RateLimit-Limit` is your total request limit during the 5 minute
window (e.g. requests/min * 5 min). The `X-RateLimit-Remaining` indicates
the number of requests remaining until your requests will be denied.
Finally, the `X-RateLimit-Reset` header contains a timestamp for when the
current window will completely reset assuming no further API requests are
made.
\ \
# HTTP Status Codes
**SUCCESSFUL STATUS CODES (2XX)**
`200 OK`
The request was successful.
`201 Created`
The resource was successfully created. Confirms a success when creating
a new account, credit, subscription, etc.
`204 No Content`
The request was successful and there is no response body.
**CLIENT ERROR STATUS CODES (4XX)**
`400 Bad Request`
The request was invalid or could not be understood by the server.
Resubmitting the request will likely result in the same error. This commonly
occurs when your XML is invalid, e.g. ampersands are not correctly encoded
in the text of your request. Please inspect the body of the response for
more details regarding the error.
`401 Unauthorized`
Your API key is missing or invalid.
`402 Payment Required`
Your Recurly account is in production mode but is not in good standing.
Please pay any outstanding invoices.
`403 Forbidden`
The login is attempting to perform an action it does not have privileges
to access. Verify your login credentials are for the appropriate account.
`404 Not Found`
The resource was not found with the given identifier. The response body
will explain which resource was not found.
`405 Method Not Allowed`
The requested method is not valid at the given URL.
`406 Not Acceptable`
The request's Accept header is not set to application/xml.
`412 Precondition Failed`
The request was unsuccessful because a condition was not met. For
example, this message may be returned if you attempt to cancel a
subscription for an account that has no subscription.
`422 Unprocessable Entity`
Could not process a POST or PUT request because the request is invalid.
See the response body for more details.
`429 Too many Requests`
You have made too many API requests in the last hour. Future API
requests will be ignored until the beginning of the next hour.
**SERVER ERROR STATUS CODES (5XX)**
`500 Internal Server Error`
The server encountered an error while processing your request and
failed.
`502 Gateway Error`
The load balancer or web server has trouble connecting to the Recurly
app. Please try the request again.
`503 Service Unavailable`
The service is temporarily unavailable. Please try the request again.
**FUTURE COMPATIBILITY**
For future compatibility, please interpret the following status code
ranges:
**200–299** as success,
**400–499** as client request errors,
**500–599** as server errors
##### 404 Not Found Responses
When a lookup, update, or delete request is requested on an object that
does not exist, the server returns `404 Not Found`:
```
Status: 404 Not Found
Content-Type: application/xml; charset=utf-8
```
```
\ not_found
\ The record could not be located.
```
##### 422 Unprocessable Entity Responses
If the requested create, update, or delete cannot be performed due to
validation errors, the server returns a `422 Unprocessable Entity` response
with either an array of the validation errors or a single error:
```
Status: 422 Unprocessable Entity
Content-Type: application/xml; charset=utf-8
```
```
\ is not a number
```
```
\ simultaneous_request
\
\ A change for subscription 3cf89f0c3fcda0b15c50134f63856d4e is
already in progress.
\
```
\ "
version: "2.29"
tags:
- name: purchases
x-displayName: Purchases
- name: accounts
x-displayName: Accounts
- name: billing-info
x-displayName: Billing Info
- name: billing-infos
x-displayName: Billing Infos
- name: shipping-addresses
x-displayName: Shipping Addresses
- name: account-acquisition
x-displayName: Account Acquisition
- name: adjustments
x-displayName: Adjustments
- name: coupons
x-displayName: Coupons
- name: coupon-redemptions
x-displayName: Coupon Redemptions
- name: custom_field_definition
x-displayName: Custom Field Definition
description: Describes the fields that can be used as custom fields on accounts, items, line-items (one time charges), plans, or subscriptions.
- name: gift-cards
x-displayName: Gift Cards
- name: invoices
x-displayName: Invoices
- name: plans
x-displayName: Plans
- name: items
x-displayName: Items
- name: plan-add-ons
x-displayName: Plan Add-Ons
- name: subscriptions
x-displayName: Subscriptions
- name: measured-units
x-displayName: Measured Units
- name: subscription-usage-records
x-displayName: Subscription Usage Records
- name: transactions
x-displayName: Transactions
- name: credit-payments
x-displayName: Credit Payments
- name: exports
x-displayName: Automated Exports
- name: shipping-fees
x-displayName: Shipping Methods
- name: dunning-campaigns
x-displayName: Dunning Campaigns
- name: invoice-templates
x-displayName: Invoice Templates
- name: external-products
x-displayName: External Products
- name: external-product-references
x-displayName: External Product References
- name: external-subscriptions
x-displayName: External Subscriptions
- name: external-invoices
x-displayName: External Invoices
- name: external-payment-phases
x-displayName: External Payment Phases
- name: external-accounts
x-displayName: External Accounts
- name: general_ledger_accounts
x-displayName: General Ledger Accounts
description: |
A general ledger account is an account of record used to sort, store
and summarize a company's transactions. Recurly supports the balance
sheet (Liability) account and income (Revenue) account to be attached
to business entities, plans, or at the item level.
When invoices are created, system can default to the accounts based
on the GL Accounts attached at the plan/item level. The accounts can
be defaulted from the business entity level as well.
These accounts will be used in the Revenue Recognition module to create
the revenue journals that can be posted into Merchant GL system.
Revenue and Liability accounts can defined in the system using this
API or via the General Ledger Accounting page in the Admin UI and then
used at the plan/item level.
Recurly allows merchants to default the accounts at the following levels:
- Business Entities (default)
- Plans
- Base Price
- Setup Fee
- Add-ons
- Items
- Charges
- Gift Cards
- Shipping Methods
- Credits
If you are interested in Recurly Revenue Recognition features, please
contact a Recurly customer service representative.
- name: performance_obligations
x-displayName: Performance Obligations
description: |
A performance obligation is a promise to provide a distinct good or
service or a series of distinct goods or services as defined by the revenue standard.
Performance obligations are completed and revenue is recognized either at a point in
time or over a period of time, depending on the type of obligation.
- Point in time a company has to go through the criteria and determine if a performance
obligation is satisfied over time. If it does not meet those criteria, then the performance
obligation is satisfied and revenue recognized at the point in time when control of the good
or service is transferred to the customer.
- Over a period of time a performance obligation is satisfied and revenue is recognized over
time if at least one of the following are met:
- The customer receives and consumes the benefits of the goods or services as they are provided
by the entity (routine, recurring services like a cleaning service are an example of a series of
services that are substantially the same and have the same pattern of transfer)
- name: business-entities
x-displayName: Business Entities
paths:
"/purchases":
post:
summary: Create Purchase
description: >+
A purchase is a checkout containing at least one or more subscriptions
or one-time charges (adjustments) and supports both coupon and gift card
redemptions. All items purchased will be on one invoice and paid for
with one transaction. A purchase is only a request data type and is not
persistent in Recurly and an invoice collection will be the returned
type. The purchases endpoint can also be used to immediately create a
credit invoice on an account, when Credit Invoices is enabled on your
site. If you plan to use a shipping address(es) for a purchase, please
see https://docs.recurly.com/docs/shipping-address-per-line-item. For
additional information regarding shipping fees, please see
https://docs.recurly.com/docs/shipping
tags:
- purchases
operationId: createPurchase
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/Purchase"
examples:
WithNewBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoNewRequest"
WithExistingBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoExistingRequest"
WithRampIntervalsOverrideRequest:
$ref: "#/components/examples/PurchaseWithRampIntervalsOverrideRequest"
WithSubscriptionAddOnsRequest:
$ref: "#/components/examples/PurchaseWithSubscriptionAddOnsRequest"
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US37c0057d2f641f4e2fcbda4b5b833633paid1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875falseLonDoner400 Alabama StSan FranciscoCA94110UShome2016-08-03T16:26:26Zfirst_liabilityfirst_revenue7ps2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenlysizelarge
x-codeSamples:
- lang: PHP
source: |-
currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";
# Create purchase with new billing info
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$purchase->account->billing_info = $billing_info;
# Or create purchase with existing billing info
$purchase->billing_info_uuid = "billingInfoUuid";
$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';
$purchase->shipping_address = $shipping_address;
$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;
$adjustment->custom_fields[] = new Recurly_CustomField('size', 'large');
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
$adjustment->performance_obligation_id = $my_pob_id;
// [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$adjustment->revenue_gl_account_id = $my_revenue_gla_id;
$adjustment->liability_gl_account_id = $my_liability_gla_id;
$purchase->adjustments = array($adjustment);
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 100),
new Recurly_SubscriptionRampInterval(2, 300),
new Recurly_SubscriptionRampInterval(4, 600)
);
$purchase->subscriptions = array($subscription);
$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;
$purchase->shipping_fees = array($shipping_fee);
$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');
$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;
// Create an invoice collection
try {
$collection = Recurly_Purchase::invoice($purchase);
} catch (Recurly_ValidationError $e) {
// You can get an idea why a purchase failed looking at these objects:
var_dump($e->errors->transaction_error); // Recurly_TransactionError
var_dump($e->errors->transaction); // Recurly_Transaction
}
- lang: Ruby
source: |-
require 'securerandom'
# Create purchase with new billing info
purchase = Recurly::Purchase.new({
currency: 'USD',
collection_method: :automatic,
account: {
account_code: SecureRandom.uuid,
billing_info: {
first_name: 'Benjamin',
last_name: 'Du Monde',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
number: '4111-1111-1111-1111',
month: 12,
year: 2019,
}
},
subscriptions: [
{
plan_code: "gold",
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals: [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 1000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 2000
}
)
]
}
],
adjustments: [
{
product_code: SecureRandom.uuid,
unit_amount_in_cents: 1_000,
quantity: 1,
revenue_schedule_type: :at_invoice,
custom_fields: [Recurly::CustomField.new(name: 'size', value: 'large')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
performance_obligation_id: pob_id,
# [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
revenue_gl_account_id: revenue_gla_id,
liability_gl_account_id: liability_gla_id,
},
],
shipping_address: {
first_name: 'Lon',
last_name: 'Dorner',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
nickname: 'home',
},
shipping_fees: [
{
shipping_method_code: 'fast_fast_fast',
shipping_amount_in_cents: '999'
}
],
coupon_codes: [
"COUPON123",
"COUPON345",
],
gift_card: {
redemption_code: "BC3749AB38371F273"
}
})
begin
collection = Recurly::Purchase.invoice!(purchase)
puts collection.inspect
rescue Recurly::Resource::Invalid => e
puts e.inspect
# Invalid data
rescue Recurly::Transaction::Error => e
puts e.inspect
# Transaction error
# e.transaction
# e.transaction_error_code
end
# Create purchase with existing billing info
purchase = Recurly::Purchase.new({
currency: 'USD',
collection_method: :automatic,
billing_info_uuid: 'billing-info-uuid',
account: {
account_code: account.account_code,
},
subscriptions: [
plan_code: plan.plan_code,
],
shipping_address: {
first_name: 'Lon',
last_name: 'Dorner',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
nickname: 'home',
}
})
collection = Recurly::Purchase.invoice!(purchase)
- lang: Python
source: |-
# Create purchase with new billing info
purchase = recurly.Purchase(
currency = 'USD',
account = recurly.Account(
account_code = 'account-code-123',
billing_info = recurly.BillingInfo(
first_name = 'Benjamin',
last_name = 'DuMonde',
number = '4111-1111-1111-1111',
verification_value = '123',
month = 11,
year = 2020,
address1 = '123 Main St',
city = 'New Orleans',
state = 'LA',
zip = '70114',
country = 'US',
)
),
subscriptions = [
recurly.Subscription(
plan_code = 'gold',
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals = [
recurly.SubRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=2000
),
recurly.SubRampInterval(
starting_billing_cycle=3,
unit_amount_in_cents=3000
)
]
)
],
adjustments = [
recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
quantity=1, custom_fields=[recurly.CustomField(name = 'size', value = 'large')]),
recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
quantity=2),
],
shipping_address = recurly.ShippingAddress(
first_name = 'Lon',
last_name = 'Dorner',
address1 = '400 Alabama St',
city = 'San Francisco',
state = 'CA',
zip = '94110',
country = 'US',
nickname = 'home'
),
shipping_fees = [
recurly.ShippingFee(
shipping_method_code = 'fast_fast_fast',
shipping_amount_in_cents = 999
)
]
)
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
purchase.adjustments[0].performance_obligation_id = performance_obligation_id
# will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
purchase.adjustments[0].liability_gl_account_id = liability_gl_account_id
purchase.adjustments[0].revenue_gl_account_id = revenue_gl_account_id
collection = purchase.invoice()
print(collection)
# Create purchase with existing billing info
purchase = recurly.Purchase(
account = account,
billing_info_uuid = "billingInfoUuid",
...
)
collection = purchase.invoice()
- lang: Dotnet
source: |-
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";
// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);
purchase.BillingInfoUuid = "billingInfoUuid"
var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.ShippingAddress = shipAddr;
// Add shipping fees
var shippingFee = new ShippingFee()
{
ShippingMethodCode = "fast_fast_fast",
ShippingAmountInCents = 999
};
purchase.ShippingFees = new List();
purchase.ShippingFees.Add(shippingFee);
// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));
// Add custom field to an adjustment if desired
purchase.Adjustments[0].CustomFields.Add(new CustomField("size", "large"));
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
purchase.Adjustments[0].PerformanceObligationId = myPobId;
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
purchase.Adjustments[0].LiabilityGlAccountId = myLiabilityGlaId;
purchase.Adjustments[0].RevenueGlAccountId = myRevenueGlaId;
var subscription = new Subscription(planCode);
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(subscription);
// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);
// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;
// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;
// Executes the purchase and transactions
var collection = Purchase.Invoice(purchase);
- lang: Java
source: |-
final Purchase purchaseData = new Purchase();
purchaseData.setAccount(account);
purchaseData.setCollectionMethod("automatic");
purchaseData.setCurrency("USD");
final Adjustment prePurchaseAdjustment = new Adjustment();
prePurchaseAdjustment.setUnitAmountInCents(350);
// Add Recurly RevRec settings to an adjustment
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
prePurchaseAdjustment.setPerformanceObligationId(pobId);
// [liability|revenue]GlaId will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
prePurchaseAdjustment.setLiabilityGlAccountId(liabilityGlaId);
prePurchaseAdjustment.setRevenueGlAccountId(revenueGlaId);
final Adjustments prePurchasedjustments = new Adjustments();
prePurchasedjustments.setRecurlyObject(prePurchaseAdjustment);
purchaseData.setAdjustments(prePurchasedjustments);
final InvoiceCollection invoiceCollection = client.Purchase(purchaseData);
System.out.println("invoiceCollection: " + invoiceCollection);
"/purchases/preview":
post:
summary: Preview Purchase
description: >+
A purchase is a hybrid checkout containing at least one or more
subscriptions or one-time charges (adjustments) and supports both coupon
and gift card redemptions. All items purchased will be on one invoice
and paid for with one transaction. A purchase is only a request data
type and is not persistent in Recurly and an invoice collection will be
the returned type.
POSTing to the preview endpoint runs the validations and creates a preview invoice, but does not run the transactions.
For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping
tags:
- purchases
operationId: previewPurchase
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/Purchase"
examples:
WithNewBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoNewRequest"
WithExistingBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoExistingRequest"
WithRampIntervalsOverrideRequest:
$ref: "#/components/examples/PurchaseWithRampIntervalsOverrideRequest"
WithSubscriptionAddOnsRequest:
$ref: "#/components/examples/PurchaseWithSubscriptionAddOnsRequest"
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLonDoner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633paid1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875false2016-08-03T16:26:26Zwidgetdoodadfirst_liabilityfirst_revenue7ps2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenly
x-codeSamples:
- lang: PHP
source: |-
currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$purchase->account->billing_info = $billing_info;
$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';
$purchase->shipping_address = $shipping_address;
$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;
$adjustment->custom_fields[] = new Recurly_CustomField('widget', 'doodad');
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
$adjustment->performance_obligation_id = $my_pob_id;
// [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$adjustment->revenue_gl_account_id = $my_revenue_gla_id;
$adjustment->liability_gl_account_id = $my_liability_gla_id;
$purchase->adjustments = array($adjustment);
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 100),
new Recurly_SubscriptionRampInterval(2, 300),
new Recurly_SubscriptionRampInterval(4, 600)
);
$purchase->subscriptions = array($subscription);
$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;
$purchase->shipping_fees = array($shipping_fee);
$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');
$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;
// Create a preview invoice collection
try {
$previewCollection = Recurly_Purchase::preview($purchase);
} catch (Recurly_ValidationError $e) {
// You can get an idea why a purchase failed looking at these objects:
var_dump($e);
}
- lang: Ruby
source: |-
require 'securerandom'
purchase = Recurly::Purchase.new({
currency: 'USD',
collection_method: :automatic,
account: {
account_code: SecureRandom.uuid,
billing_info: {
first_name: 'Benjamin',
last_name: 'Du Monde',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
number: '4111-1111-1111-1111',
month: 12,
year: 2019,
}
},
subscriptions: [
{
plan_code: "gold",
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals: [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 1000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 2000
}
)
]
}
],
adjustments: [
{
product_code: SecureRandom.uuid,
unit_amount_in_cents: 1_000,
quantity: 1,
revenue_schedule_type: :at_invoice,
custom_fields: [Recurly::CustomField.new(name: 'widget', value: 'doodad')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
performance_obligation_id: pob_id,
# [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
revenue_gl_account_id: revenue_gla_id,
liability_gl_account_id: liability_gla_id
},
],
shipping_address: {
first_name: 'Lon',
last_name: 'Dorner',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
nickname: 'home',
},
shipping_fees: [
{
shipping_method_code: 'fast_fast_fast',
shipping_amount_in_cents: '999'
}
],
coupon_codes: [
"COUPON123",
"COUPON345",
],
gift_card: {
redemption_code: "BC3749AB38371F273"
}
})
begin
preview_collection = Recurly::Purchase.preview!(purchase)
puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
puts e.inspect
# Invalid data
end
- lang: Python
source: |-
purchase = recurly.Purchase(
currency = 'USD',
account = recurly.Account(
account_code = 'account-code-123',
billing_info = recurly.BillingInfo(
first_name = 'Benjamin',
last_name = 'DuMonde',
number = '4111-1111-1111-1111',
verification_value = '123',
month = 11,
year = 2020,
address1 = '123 Main St',
city = 'New Orleans',
state = 'LA',
zip = '70114',
country = 'US',
)
),
subscriptions = [
recurly.Subscription(
plan_code = 'gold',
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals = [
recurly.SubRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=2000
),
recurly.SubRampInterval(
starting_billing_cycle=3,
unit_amount_in_cents=3000
)
]
)
],
adjustments = [
recurly.Adjustment(unit_amount_in_cents=1000,
description='Item 1',
quantity=1,
custom_fields=[recurly.CustomField(name = 'widget', value = 'doodad')]),
),
recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
quantity=2),
],
shipping_address = recurly.ShippingAddress(
first_name = 'Lon',
last_name = 'Dorner',
address1 = '400 Alabama St',
city = 'San Francisco',
state = 'CA',
zip = '94110',
country = 'US',
nickname = 'home'
),
shipping_fees = [
recurly.ShippingFee(
shipping_method_code = 'fast_fast_fast',
shipping_amount_in_cents = 999
)
]
)
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
purchase.adjustments[0].performance_obligation_id = performance_obligation_id
# will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
purchase.adjustments[0].liability_gl_account_id = liability_gl_account_id
purchase.adjustments[0].revenue_gl_account_id = revenue_gl_account_id
preview_collection = purchase.preview()
print(preview_collection)
- lang: Dotnet
source: |-
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";
// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);
var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.ShippingAddress = shipAddr;
// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));
// Add custom field to an adjustment
purchase.Adjustments[0].CustomFields.Add(new CustomField("widget", "doodad"));
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
purchase.Adjustments[0].PerformanceObligationId = myPobId;
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
purchase.Adjustments[0].LiabilityGlAccountId = myLiabilityGlaId;
purchase.Adjustments[0].RevenueGlAccountId = myRevenueGlaId;
var subscription = new Subscription(planCode);
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(subscription);
// Add shipping fees
var shippingFee = new ShippingFee()
{
ShippingMethodCode = "fast_fast_fast",
ShippingAmountInCents = 999
};
purchase.ShippingFees = new List();
purchase.ShippingFees.Add(shippingFee);
// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);
// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;
// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;
// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Preview(purchase);
- lang: Java
source: |-
final Purchase purchaseData = new Purchase();
purchaseData.setAccount(account);
purchaseData.setCollectionMethod("automatic");
purchaseData.setCurrency("USD");
final Adjustment prePurchaseAdjustment = new Adjustment();
prePurchaseAdjustment.setUnitAmountInCents(350);
// Add Recurly RevRec settings to an adjustment
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
prePurchaseAdjustment.setPerformanceObligationId(pobId);
// [liability|revenue]GlaId will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
prePurchaseAdjustment.setLiabilityGlAccountId(liabilityGlaId);
prePurchaseAdjustment.setRevenueGlAccountId(revenueGlaId);
final Adjustments prePurchasedjustments = new Adjustments();
prePurchasedjustments.setRecurlyObject(prePurchaseAdjustment);
purchaseData.setAdjustments(prePurchasedjustments);
final InvoiceCollection invoiceCollection = client.previewPurchase(purchaseData);
System.out.println("invoiceCollection: " + invoiceCollection);
"/purchases/authorize":
post:
summary: Authorize Purchase
description: >+
A purchase is a hybrid checkout containing at least one or more
subscriptions or one-time charges (adjustments) and supports both coupon
and gift card redemptions. All items purchased will be on one invoice
and paid for with one transaction. A purchase is only a request data
type and is not persistent in Recurly and an invoice collection will be
the returned type.
The authorize endpoint will create a pending purchase that can be activated at a later time once payment has been completed on an external source (e.g. Adyen's Hosted Payment Pages).
For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping
tags:
- purchases
operationId: authorizePurchase
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/Purchase"
examples:
WithNewBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoNewRequest"
WithExistingBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoExistingRequest"
WithRampIntervalsOverrideRequest:
$ref: "#/components/examples/PurchaseWithRampIntervalsOverrideRequest"
WithSubscriptionAddOnsRequest:
$ref: "#/components/examples/PurchaseWithSubscriptionAddOnsRequest"
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLonDoner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633paid1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875false2016-08-03T16:26:26Zfirst_liabilityfirst_revenue7ps2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenlysizelarge
x-codeSamples:
- lang: PHP
source: |-
currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$purchase->account->billing_info = $billing_info;
$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';
$purchase->account->shipping_addresses = array($shipping_address);
$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;
$adjustment->custom_fields[] = new Recurly_CustomField('size', 'large');
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
$adjustment->performance_obligation_id = $my_pob_id;
// [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$adjustment->revenue_gl_account_id = $my_revenue_gla_id;
$adjustment->liability_gl_account_id = $my_liability_gla_id;
$purchase->adjustments = array($adjustment);
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 100),
new Recurly_SubscriptionRampInterval(2, 300),
new Recurly_SubscriptionRampInterval(4, 600)
);
$purchase->subscriptions = array($subscription);
$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;
$purchase->shipping_fees = array($shipping_fee);
$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');
$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;
// Create a preview invoice collection
try {
$previewCollection = Recurly_Purchase::authorize($purchase);
} catch (Recurly_ValidationError $e) {
// You can get an idea why a purchase failed looking at these objects:
var_dump($e);
}
- lang: Ruby
source: |-
require 'securerandom'
purchase = Recurly::Purchase.new({
currency: 'USD',
collection_method: :automatic,
account: {
account_code: SecureRandom.uuid,
billing_info: {
first_name: 'Benjamin',
last_name: 'Du Monde',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
number: '4111-1111-1111-1111',
month: 12,
year: 2019,
},
shipping_addresses: [
{
first_name: 'Lon',
last_name: 'Dorner',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
nickname: 'home',
}
]
},
subscriptions: [
{
plan_code: "gold",
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals: [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 1000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 2000
}
)
]
}
],
adjustments: [
{
product_code: SecureRandom.uuid,
unit_amount_in_cents: 1_000,
quantity: 1,
revenue_schedule_type: :at_invoice,
custom_fields: [Recurly::CustomField.new(name: 'size', value: 'large')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
performance_obligation_id: pob_id,
# [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
revenue_gl_account_id: revenue_gla_id,
liability_gl_account_id: liability_gla_id
},
],
shipping_fees: [
{
shipping_method_code: 'fast_fast_fast',
shipping_amount_in_cents: '999'
}
],
coupon_codes: [
"COUPON123",
"COUPON345",
],
gift_card: {
redemption_code: "BC3749AB38371F273"
}
})
begin
preview_collection = Recurly::Purchase.authorize!(purchase)
puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
puts e.inspect
# Invalid data
end
- lang: Python
source: |-
purchase = recurly.Purchase(
currency = 'USD',
account = recurly.Account(
account_code = 'account-code-123',
billing_info = recurly.BillingInfo(
first_name = 'Benjamin',
last_name = 'DuMonde',
number = '4111-1111-1111-1111',
verification_value = '123',
month = 11,
year = 2020,
address1 = '123 Main St',
city = 'New Orleans',
state = 'LA',
zip = '70114',
country = 'US',
),
shipping_addresses = [
recurly.ShippingAddress(
first_name = 'Lon',
last_name = 'Dorner',
address1 = '400 Alabama St',
city = 'San Francisco',
state = 'CA',
zip = '94110',
country = 'US',
nickname = 'home'
)
]
),
subscriptions = [
recurly.Subscription(
plan_code = 'gold',
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals = [
recurly.SubRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=2000
),
recurly.SubRampInterval(
starting_billing_cycle=3,
unit_amount_in_cents=3000
)
]
)
],
adjustments = [
recurly.Adjustment(unit_amount_in_cents=1000,
description='Item 1',
quantity=1,
custom_fields=[recurly.CustomField(name = 'size', value = 'large')]),
recurly.Adjustment(unit_amount_in_cents=2000,
description='Item 2',
quantity=2),
],
shipping_fees = [
recurly.ShippingFee(
shipping_method_code = 'fast_fast_fast',
shipping_amount_in_cents = 999
)
]
)
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
purchase.adjustments[0].performance_obligation_id = performance_obligation_id
# will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
purchase.adjustments[0].liability_gl_account_id = liability_gl_account_id
purchase.adjustments[0].revenue_gl_account_id = revenue_gl_account_id
preview_collection = purchase.authorize()
print(preview_collection)
- lang: Dotnet
source: |-
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";
// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);
var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);
// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));
// Add custom field to an adjustment
purchase.Adjustments[0].CustomFields.Add(new CustomField("size", "large"));
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
purchase.Adjustments[0].PerformanceObligationId = myPobId;
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
purchase.Adjustments[0].LiabilityGlAccountId = myLiabilityGlaId;
purchase.Adjustments[0].RevenueGlAccountId = myRevenueGlaId;
var subscription = new Subscription(planCode);
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(subscription);
// Add shipping fees
var shippingFee = new ShippingFee()
{
ShippingMethodCode = "fast_fast_fast",
ShippingAmountInCents = 999
};
purchase.ShippingFees = new List();
purchase.ShippingFees.Add(shippingFee);
// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);
// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;
// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;
// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Authorize(purchase);
- lang: Java
source: |-
final Purchase purchaseData = new Purchase();
purchaseData.setAccount(account);
purchaseData.setCollectionMethod("automatic");
purchaseData.setCurrency("USD");
final Adjustment prePurchaseAdjustment = new Adjustment();
prePurchaseAdjustment.setUnitAmountInCents(350);
// Add Recurly RevRec settings to an adjustment
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
prePurchaseAdjustment.setPerformanceObligationId(pobId);
// [liability|revenue]GlaId will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
prePurchaseAdjustment.setLiabilityGlAccountId(liabilityGlaId);
prePurchaseAdjustment.setRevenueGlAccountId(revenueGlaId);
final Adjustments prePurchasedjustments = new Adjustments();
prePurchasedjustments.setRecurlyObject(prePurchaseAdjustment);
purchaseData.setAdjustments(prePurchasedjustments);
final InvoiceCollection invoiceCollection = client.authorizePurchase(purchaseData);
System.out.println("invoiceCollection: " + invoiceCollection);
"/purchases/pending":
post:
summary: Pending Purchase
description: >+
A purchase is a hybrid checkout containing at least one or more
subscriptions or one-time charges (adjustments) and supports both coupon
and gift card redemptions. All items purchased will be on one invoice
and paid for with one transaction. A purchase is only a request data
type and is not persistent in Recurly and an invoice collection will be
the returned type.
Use for **Adyen HPP** and **Online Banking** transaction requests.
This runs the validations but not the transactions.
The API request allows the inclusion of the following field: **external_hpp_type** with `'adyen'` in the **billing_info** object.
For additional information regarding shipping fees, please see https://docs.recurly.com/docs/shipping
tags:
- purchases
operationId: pendingPurchase
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/Purchase"
examples:
WithNewBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoNewRequest"
WithExistingBillingInfoRequest:
$ref: "#/components/examples/PurchaseWithBillingInfoExistingRequest"
WithRampIntervalsOverrideRequest:
$ref: "#/components/examples/PurchaseWithRampIntervalsOverrideRequest"
WithSubscriptionAddOnsRequest:
$ref: "#/components/examples/PurchaseWithSubscriptionAddOnsRequest"
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLonDoner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633paid1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875false2016-08-03T16:26:26Zfirst_liabilityfirst_revenue7ps2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenlysizelarge
x-codeSamples:
- lang: PHP
source: |-
currency = 'USD';
$purchase->collection_method = 'automatic';
$purchase->account = new Recurly_Account();
$purchase->account->account_code = 'aba9209a-aa61-4790-8e61-0a2692435fee';
$purchase->account->email = "verena@example.com";
$purchase->account->first_name = "Benjamin";
$purchase->account->last_name = "Du Monde";
$purchase->account->address->phone = "555-555-5555";
$purchase->account->address->address1 = "123 Main St.";
$purchase->account->address->city = "San Francisco";
$purchase->account->address->state = "CA";
$purchase->account->address->zip = "94110";
$purchase->account->address->country = "US";
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$purchase->account->billing_info = $billing_info;
$shipping_address = new Recurly_ShippingAddress();
$shipping_address->first_name = 'Lon';
$shipping_address->last_name = 'Dorner';
$shipping_address->address1 = '400 Dolores St';
$shipping_address->city = 'San Francisco';
$shipping_address->state = 'CA';
$shipping_address->country = 'US';
$shipping_address->zip = '94110';
$shipping_address->nickname = 'Home';
$purchase->account->shipping_addresses = array($shipping_address);
$adjustment = new Recurly_Adjustment();
$adjustment->unit_amount_in_cents = 1000;
$adjustment->quantity = 1;
$adjustment->custom_fields[] = new Recurly_CustomField('size', 'large');
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
$adjustment->performance_obligation_id = $my_pob_id;
// [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$adjustment->revenue_gl_account_id = $my_revenue_gla_id;
$adjustment->liability_gl_account_id = $my_liability_gla_id;
$purchase->adjustments = array($adjustment);
$subscription = new Recurly_Subscription();
$subscription->plan_code = 'pp';
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 100),
new Recurly_SubscriptionRampInterval(2, 300),
new Recurly_SubscriptionRampInterval(4, 600)
);
$purchase->subscriptions = array($subscription);
$shipping_fee = new Recurly_ShippingFee();
$shipping_fee->shipping_method_code = 'fast_fast_fast';
$shipping_fee->shipping_amount_in_cents = 999;
$purchase->coupon_codes = array('couponcode123', 'rqw311ofo6');
$gift_card = new Recurly_GiftCard();
$gift_card->redemption_code = "FCJ7GEY4HO8WR16Q";
$purchase->gift_card = $gift_card;
// Create a preview invoice collection
try {
$previewCollection = Recurly_Purchase::pending($purchase);
} catch (Recurly_ValidationError $e) {
// You can get an idea why a purchase failed looking at these objects:
var_dump($e);
}
- lang: Ruby
source: |-
require 'securerandom'
purchase = Recurly::Purchase.new({
currency: 'USD',
collection_method: :automatic,
account: {
account_code: SecureRandom.uuid,
billing_info: {
first_name: 'Benjamin',
last_name: 'Du Monde',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
number: '4111-1111-1111-1111',
month: 12,
year: 2019,
},
shipping_addresses: [
{
first_name: 'Lon',
last_name: 'Dorner',
address1: '400 Alabama St',
city: 'San Francisco',
state: 'CA',
zip: '94110',
country: 'US',
nickname: 'home',
}
]
},
subscriptions: [
{
plan_code: "gold",
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals: [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 1000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 2000
}
)
]
}
],
adjustments: [
{
product_code: SecureRandom.uuid,
unit_amount_in_cents: 1_000,
quantity: 1,
revenue_schedule_type: :at_invoice,
custom_fields: [Recurly::CustomField.new(name: 'size', value: 'large')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
performance_obligation_id: pob_id,
# [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
revenue_gl_account_id: revenue_gla_id,
liability_gl_account_id: liability_gla_id
},
],
shipping_fees: [
{
shipping_method_code: 'fast_fast_fast',
shipping_amount_in_cents: '999'
}
],
coupon_codes: [
"COUPON123",
"COUPON345",
],
gift_card: {
redemption_code: "BC3749AB38371F273"
}
})
begin
preview_collection = Recurly::Purchase.pending!(purchase)
puts preview_collection.inspect
rescue Recurly::Resource::Invalid => e
puts e.inspect
# Invalid data
end
- lang: Python
source: |-
purchase = recurly.Purchase(
currency = 'USD',
account = recurly.Account(
account_code = 'account-code-123',
billing_info = recurly.BillingInfo(
first_name = 'Benjamin',
last_name = 'DuMonde',
number = '4111-1111-1111-1111',
verification_value = '123',
month = 11,
year = 2020,
address1 = '123 Main St',
city = 'New Orleans',
state = 'LA',
zip = '70114',
country = 'US',
),
shipping_addresses = [
recurly.ShippingAddress(
first_name = 'Lon',
last_name = 'Dorner',
address1 = '400 Alabama St',
city = 'San Francisco',
state = 'CA',
zip = '94110',
country = 'US',
nickname = 'home'
)
]
),
subscriptions = [
recurly.Subscription(
plan_code = 'gold',
# if purchasing ramp-priced subscription and overriding
# ramps is desired:
ramp_intervals = [
recurly.SubRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=2000
),
recurly.SubRampInterval(
starting_billing_cycle=3,
unit_amount_in_cents=3000
)
]
)
],
adjustments = [
recurly.Adjustment(unit_amount_in_cents=1000, description='Item 1',
quantity=1, custom_fields=[recurly.CustomField(name = 'size', value = 'large')]),
recurly.Adjustment(unit_amount_in_cents=2000, description='Item 2',
quantity=2),
],
shipping_fees = [
recurly.ShippingFee(
shipping_method_code = 'fast_fast_fast',
shipping_amount_in_cents = 999
)
]
)
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
purchase.adjustments[0].performance_obligation_id = performance_obligation_id
# will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
purchase.adjustments[0].liability_gl_account_id = liability_gl_account_id
purchase.adjustments[0].revenue_gl_account_id = revenue_gl_account_id
preview_collection = purchase.pending()
print(preview_collection)
- lang: Dotnet
source: |-
var accountCode = "benjamin-du-monde";
var currency = "USD";
var planCode = "surveillance-pro";
var couponCode = "surveillance-podcast-promo";
var giftCardRedemptionCode = "8Z5VE6IRMWJDHU4P";
// We can create a purchase object from an account code or an Account object (first argument).
// Use the Account object when you want create a new account. This works similar to Subscription.
var purchase = new Purchase(accountCode, currency);
var shipAddr = new ShippingAddress();
shipAddr.Address1 = "400 Alabama St";
shipAddr.City = "San Francisco";
shipAddr.State = "CA";
shipAddr.Country = "US";
shipAddr.Zip = "94110";
shipAddr.FirstName = "Lon";
shipAddr.LastName = "Dorner";
shipAddr.Nickname = "home";
purchase.Account.ShippingAddresses.Add(shipAddr);
// Add multiple adjustments (optional if subscription[s] included)
purchase.Adjustments.Add(new Adjustment(4000, "HD Camera", 5));
purchase.Adjustments.Add(new Adjustment(1000, "Motion Sensor", 10));
// Add custom field to an adjustment if desired
purchase.Adjustments[0].CustomFields.Add(new CustomField("size", "large"));
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
purchase.Adjustments[0].PerformanceObligationId = myPobId;
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
purchase.Adjustments[0].LiabilityGlAccountId = myLiabilityGlaId;
purchase.Adjustments[0].RevenueGlAccountId = myRevenueGlaId;
var subscription = new Subscription(planCode);
// if purchasing ramp-priced subscription and overriding
// ramps is desired:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
// Add multiple subscriptions (optional if adjustment[s] included)
purchase.Subscriptions.Add(subscription);
// Add shipping fees
var shippingFee = new ShippingFee()
{
ShippingMethodCode = "fast_fast_fast",
ShippingAmountInCents = 999
};
purchase.ShippingFees = new List();
purchase.ShippingFees.Add(shippingFee);
// Add multiple coupon codes the customer may have (optional)
purchase.CouponCodes.Add(couponCode);
// Redeem a gift card with this purchase if the customer has redemption code (optional)
purchase.GiftCardRedemptionCode = giftCardRedemptionCode;
// For manual invoicing
// purchase.CollectionMethod = Invoice.Collection.Manual;
// purchase.NetTerms = 30;
// Previewing allows us to run all calculations and validations without running the
// transactions yet. This allows us to check the information and show the customer
// the the detailed invoices before they confirm the purchase.
var previewCollection = Purchase.Pending(purchase);
- lang: Java
source: |-
final Purchase purchaseData = new Purchase();
purchaseData.setAccount(account);
purchaseData.setCollectionMethod("automatic");
purchaseData.setCurrency("USD");
final Adjustment prePurchaseAdjustment = new Adjustment();
prePurchaseAdjustment.setUnitAmountInCents(350);
// Add Recurly RevRec settings to an adjustment
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
prePurchaseAdjustment.setPerformanceObligationId(pobId);
// [liability|revenue]GlaId will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
prePurchaseAdjustment.setLiabilityGlAccountId(liabilityGlaId);
prePurchaseAdjustment.setRevenueGlAccountId(revenueGlaId);
final Adjustments prePurchasedjustments = new Adjustments();
prePurchasedjustments.setRecurlyObject(prePurchaseAdjustment);
purchaseData.setAdjustments(prePurchasedjustments);
final InvoiceCollection invoiceCollection = client.pendingPurchase(purchaseData);
System.out.println("invoiceCollection: " + invoiceCollection);
"/purchases/transaction-uuid-{transaction_uuid}/capture":
parameters:
- $ref: "#/components/parameters/transaction_uuid"
post:
summary: Capture Purchase
description: >+
A purchase is a hybrid checkout containing at least one or more
subscriptions or one-time charges (adjustments) and supports both coupon
and gift card redemptions. All items purchased will be on one invoice
and paid for with one transaction. A purchase is only a request data
type and is not persistent in Recurly and an invoice collection will be
the returned type.
Capture an open Authorization request
tags:
- purchases
operationId: capturePurchase
parameters:
- in: path
name: transaction_uuid
schema:
type: string
required: true
description: Transaction Uuid.
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLonDoner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633paid1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875false2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenlysizelarge
x-codeSamples:
- lang: Ruby
source: >-
purchase = Recurly::Purchase.new({
# see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
})
authorized_purchase = Recurly::Purchase.authorize!(purchase)
transaction_uuid = authorized_purchase.charge_invoice.transactions.first.uuid
captured_collection = Purchase.capture!(transaction_uuid)
- lang: Python
source: >-
purchase = recurly.Purchase(
# see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
)
authorized = purchase.authorize()
transaction_uuid = authorized.charge_invoice.transactions[0].uuid
captured_collection = purchase.capture(transaction_uuid)
- lang: PHP
source: >-
charge_invoice->transactions->current()->uuid;
$captured_collection = $purchase->capture($transaction_uuid);
- lang: Dotnet
source: >
purchase = new Purchase(
// see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
);
var authorized = Purchase.Authorize(purchase);
var transactionUuid = authorized.ChargeInvoice.Transactions[0].Uuid;
var capturedCollection = Purchase.Capture(transactionUuid);
"/purchases/transaction-uuid-{transaction_uuid}/cancel":
parameters:
- $ref: "#/components/parameters/transaction_uuid"
post:
summary: Cancel Purchase
description: >+
A purchase is a hybrid checkout containing at least one or more
subscriptions or one-time charges (adjustments) and supports both coupon
and gift card redemptions. All items purchased will be on one invoice
and paid for with one transaction. A purchase is only a request data
type and is not persistent in Recurly and an invoice collection will be
the returned type.
Cancel an open Authorization request
tags:
- purchases
operationId: cancelPurchase
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLonDoner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633failed1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue37c0057d2a3ace0c3f3d674ae89fdabdinvoicedSetup fee: Gold plangoldsetup_fee8001070870EURfalseusstCA0.0875false2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26Zevenlysizelarge
x-codeSamples:
- lang: Ruby
source: >-
purchase = Recurly::Purchase.new({
# see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
})
authorized_purchase = Recurly::Purchase.authorize!(purchase)
transaction_uuid = authorized_purchase.charge_invoice.transactions.first.uuid
canceled_collection = Purchase.cancel!(transaction_uuid)
- lang: Python
source: >-
purchase = recurly.Purchase(
# see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
)
authorized = purchase.authorize()
transaction_uuid = authorized.charge_invoice.transactions[0].uuid
canceled_collection = purchase.cancel(transaction_uuid)
- lang: PHP
source: >-
charge_invoice->transactions->current()->uuid;
$captured_collection = $purchase->cancel($transaction_uuid);
- lang: Dotnet
source: >-
purchase = new Purchase(
// see https://recurly.com/developers/api-v2/latest/#operation/createPurchase
);
var authorized = Purchase.Authorize(purchase);
var transactionUuid = previewCollection.ChargeInvoice.Transactions[0].Uuid;
var cancelledCollection = Purchase.Cancel(transactionUuid);
"/accounts":
get:
summary: List Accounts
description:
"Returns a list of accounts on your site. Results are ordered by
the time created, sorted by newest first.
**Account Query States**
| state | description |
| --- | --- |
| `active` | Open accounts. |
| `closed` | Accounts that are not open. |
| `subscriber` | Accounts with subscriptions that are valid for
the current time. This includes subscriptions in a trial period. |
| `non_subscriber` | Accounts without subscriptions that are
valid for the current time. |
| `past_due` | Accounts with invoices that have failed initial
collection but still have collection attempts remaining. |
Please note: a queried state and the base state of a returned
account may differ. For example, querying for `past_due` account will
not result in a list of accounts with a `past_due` state (they will
either be `active` or `closed`). Only base states (`active`, `closed`)
will be present in the returned account records.
\ "
tags:
- accounts
operationId: listAccounts
parameters:
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of accounts to return: `active`, `closed`, `subscriber`,
`non_subscriber`, `past_due`."
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: integer
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
schema:
type: array
items:
$ref: "#/components/schemas/Account"
xml:
name: accounts
example: >-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleNew Company Nameen-USAmerica/Los_Angelesfalse123 Main St.San FranciscoCA94105USsizelarge71c122cb16fc90252ff845eacf5d78142016-08-03T15:44:05Z2017-03-15T21:22:18Zfalsefalsefalsefalsefalse
x-codeSamples:
- lang: PHP
source: |
-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleRecurly Incen-USAmerica/Los_Angelesfalse123 Main St.San FranciscoCA94105USsizelarge3ed66441313a90bd7e8039b31985dee82016-06-14T16:08:41Z2016-08-03T16:30:50Zfalsefalsefalsefalsefalseiiznlrvdt8p1
schema:
$ref: "#/components/schemas/Account"
x-codeSamples:
- lang: xml
source: |-
12verena@example.comVerenaExampleverena1234bob@example.com,susan@example.comRecurly Incen-USAmerica/Los_Angeles123 Main St.San FranciscoCA94105USWorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101San FranciscoCA94105USHomeVerenaExample555-867-5309verena@example.com123 Fourth St.Apt. 101San FranciscoCA94105USei7nj4ddt65wiiznlrvdt8p1sizelargestringAppleAppStore
- lang: PHP
source: |-
email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';
// work shipping address
$shad1 = new Recurly_ShippingAddress();
$shad1->nickname = "Work";
$shad1->first_name = "Verena";
$shad1->last_name = "Example";
$shad1->company = "Recurly Inc.";
$shad1->phone = "555-555-5555";
$shad1->email = "verena@example.com";
$shad1->address1 = "123 Main St.";
$shad1->city = "San Francisco";
$shad1->state = "CA";
$shad1->zip = "94110";
$shad1->country = "US";
// home shipping address
$shad2 = new Recurly_ShippingAddress();
$shad2->nickname = "Home";
$shad2->first_name = "Verena";
$shad2->last_name = "Example";
$shad2->phone = "555-555-5555";
$shad2->email = "verena@example.com";
$shad2->address1 = "123 Dolores St.";
$shad2->city = "San Francisco";
$shad2->state = "CA";
$shad2->zip = "94110";
$shad2->country = "US";
$account->shipping_addresses = array($shad1, $shad2);
$account->create();
print "Account: $account\n";
} catch (Recurly_ValidationError $e) {
print "Invalid Account: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.create(
:account_code => '1',
:email => 'verena@example.com',
:first_name => 'Verena',
:last_name => 'Example',
:external_accounts => [
{ external_connection_type: 'GooglePlayStore',
external_account_code: '123'
}
]
:shipping_addresses => [
{
:nickname => 'Work',
:first_name => 'Verena',
:last_name => 'Example',
:company => 'Recurly Inc',
:phone => '555-222-1212',
:email => 'verena@example.com',
:address1 => '123 Main St.',
:address2 => 'Suite 101',
:city => 'San Francisco',
:state => 'CA',
:zip => '94105',
:country => 'US'
},
{
:nickname => 'Home',
:first_name => 'Verena',
:last_name => 'Example',
:phone => '555-867-5309',
:email => 'verena@example.com',
:address1 => '123 Fourth St.',
:address2 => 'Apt. 101',
:city => 'San Francisco',
:state => 'CA',
:zip => '94105',
:country => 'US'
}
]
)
- lang: Python
source: |-
account = recurly.Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'
account.save()
- lang: Dotnet
source: |-
var account = new Account("1")
{
Email = "verena@example.com",
FirstName = "Verena",
LastName = "Example"
};
account.Create();
"/accounts/{account_code}":
get:
summary: Lookup Account
description: |+
Returns information about a single account.
tags:
- accounts
operationId: lookupAccount
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleNew Company Nameen-USAmerica/Los_Angelesfalse123 Main St.San FranciscoCA94105USsizelarge71c122cb16fc90252ff845eacf5d78142016-08-03T15:44:05Z2017-03-15T21:22:18Zfalsefalsefalsefalsefalse
schema:
$ref: "#/components/schemas/Account"
x-codeSamples:
- lang: PHP
source: |-
e
puts e.message
end
- lang: Python
source: |-
try:
account = recurly.Account.get('1')
print "Account: %s" % account
except NotFoundError:
print "Account not found.\n"
- lang: Dotnet
source: |-
try
{
var account = Accounts.Get("1");
Console.WriteLine("Account " + account);
}
catch (NotFoundException e)
{
Console.WriteLine("Account not found.");
}
put:
summary: Update Account
description: "Updates an existing account.
###### Please note
You may optionally include billing information when updating an
account. If the billing information is provided, the billing information
will be validated. The account will only be updated if the billing
information is valid.
\ "
tags:
- accounts
operationId: updateAccount
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
parent_account_code:
type: string
default: ""
description:
The account code of the new parent account. Allows associating a
new account to an existing account as its child. Sending an
empty tag will remove an associated
parent account from an existing account
username:
type: string
default: ""
description:
The username for the account, ignore if you do not use usernames.
Max of 255 characters.
email:
type: string
default: ""
description: The email address for the account.
first_name:
type: string
default: ""
description: The first name for the account. Max of 255 characters.
last_name:
type: string
default: ""
description: The last name for the account. Max of 255 characters.
company_name:
type: string
default: ""
description: The company name for the account. Max of 50 characters.
vat_number:
type: string
default: ""
description: The VAT number to avoid having the VAT applied (if applicable).
tax_exempt:
type: boolean
default: ""
description:
The tax status of the account. `true` exempts tax on the account,
`false` applies tax on the account.
entity_use_code:
type: string
default: ""
description:
The Avalara AvaTax value that can be passed to identify the
customer type for tax purposes. The range of values can be A
- R (more info at Avalara). Value is case-sensitive.
account_acquisition:
type: object
default: ""
description:
"The nested account acquisition information: `cost_in_cents`,
currency`, `channel`, `subchannel`, `campaign`"
billing_info:
type: object
default: ""
description:
The nested billing information. If present, the account will only
be created after the billing information is validated.
address:
type: object
default: ""
description:
"The nested address information for the account: `address1`,
`address2`, `city`, `state`, `zip`, `country`, `phone`."
accept_language:
type: string
default: ""
description:
The ISO 639-1 language code from the user's browser, indicating
their preferred language and locale.
cc_emails:
type: string
default: ""
description:
Additional email address that should receive account
correspondence. These should be separated only by commas.
These CC emails will receive all emails that the `email`
field also receives.
preferred_locale:
type: string
default: ""
description:
Used to determine the language and locale of emails sent on behalf
of the merchant to the customer. The list of locales is
restricted to those the merchant has enabled on the site.
preferred_time_zone:
type: string
default: ""
description:
Used to determine the time zone of emails sent on behalf of
the merchant to the customer. Must be a [supported IANA time zone name](https://docs.recurly.com/docs/email-time-zones-and-time-stamps#supported-api-iana-time-zone-names)
invoice_template_uuid:
type: string
title: Invoice Template UUID
description:
Unique ID to identify an invoice template. Available when
the site is on a Pro or Elite plan. Used to specify which invoice
template, if any, should be used to generate invoices for the account.
dunning_campaign_id:
type: string
title: Dunning Campaign ID
description:
Unique ID to identify a dunning campaign. Available when the
Dunning Campaigns feature is enabled. Used to specify if a non-default
dunning campaign should be assigned to this account. For sites without
multiple dunning campaigns enabled, the default dunning campaign will
always be used.
override_business_entity_id:
type: string
title: Override Business Entity ID
description:
Unique ID to identify the business entity assigned to the account.
Available when the `Multiple Business Entities` feature is enabled.
custom_fields:
$ref: "#/components/schemas/CustomFields"
responses:
"200":
description: ""
content:
application/xml:
example: >-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleNew Company Nameen-USAmerica/Los_Angelesfalse123 Main St.San FranciscoCA94105USsizelarge71c122cb16fc90252ff845eacf5d78142016-08-03T15:44:05Z2016-08-03T16:30:50Zfalsefalsefalsefalsefalseiiznlrvdt8p3
schema:
$ref: "#/components/schemas/Account"
x-codeSamples:
- lang: xml
source: |-
New Company Name
- lang: PHP
source: |-
company_name = 'New Company Name';
$account->update();
print "Account: $account\n";
} catch (Recurly_NotFoundError $e) {
print "Invalid account code: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('account_1')
account.company_name = 'New Company Name'
account.save
- lang: Python
source: |-
account = recurly.Account.get('account_1')
account.company_name = 'New Company Name'
account.save()
- lang: Dotnet
source: |-
var account = Account.Get("account_1");
account.CompanyName = 'New Company Name'
account.Update();
delete:
summary: Close Account
description:
"Marks an account as closed and cancels any active subscriptions.
Paused subscriptions will be expired.
###### Please note
Closing an account permanently deletes its billing information
and cancels any active subscriptions (canceled subscriptions will remain
active until the end of the current billing cycle before expiring).
Reopening an account will restore its history. Reopening an
account does not modify any previously canceled or expired subscriptions
and billing information will need to be provided by the customer to
continue billing.
\ "
tags:
- accounts
operationId: reopenAccount
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleNew Company Nameen-USAmerica/Los_Angelesfalse123 Main St.San FranciscoCA94105USsizelarge71c122cb16fc90252ff845eacf5d78142016-08-03T15:44:05Z2016-08-03T16:31:25Z
schema:
$ref: "#/components/schemas/Account"
x-codeSamples:
- lang: PHP
source: |-
reopen();
// Or to fetch and reopen in one call
// $account = Recurly_Account::reopenAccount('b6f5783');
print "Account: $account";
} catch (Recurly_NotFoundError $e) {
print "Invalid account code: $e";
} catch (Recurly_ValidationError $e) {
print "Account already open: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find '1'
account.reopen
- lang: Python
source: |-
account = recurly.Account.get('1')
account.reopen()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
account.Reopen();
"/accounts/{account_code}/balance":
get:
summary: Lookup Account Balance
description: >+
Returns the account's past due status and balance in each of the site's
supported currencies as well as the amounts for any processing prepayment balances.
tags:
- accounts
operationId: lookupAccountBalance
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
false30000-50000-25000
"400":
description: ""
content:
application/xml:
example: >-
unavailable_in_api_versionThis request cannot be completed using this version of the API. It was added in version '2.3'.
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code = not-1
x-codeSamples:
- lang: PHP
source: |-
+
Returns a list of the notes on an account sorted in descending order
(most recently created first).
tags:
- accounts
operationId: listAccountNotes
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description: ""
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
example: >-
This is my second note2015-06-14T16:08:41ZThis is my first note2016-06-13T16:06:21Z
x-codeSamples:
- lang: PHP
source: |-
message}\n";
}
} catch (Recurly_NotFoundError $e) {
print "Invalid account code: $e";
}
- lang: Ruby
source: |-
acct = Recurly::Account.find '1'
acct.notes.each do |note|
puts note.inspect
end
- lang: Python
source: |-
try:
account = recurly.Account.get('1')
for note in account.notes():
print "Note: %s" % note.message
except NotFoundError:
print "Account not found.\n"
- lang: Dotnet
source: |-
using System.Linq;
var account = Accounts.Get("1");
var notes = account.GetNotes();
while (notes.Any())
{
foreach (var note in notes)
Console.WriteLine("Note: " + note.Message);
notes = notes.Next;
}
"/accounts/{account_code}/billing_info":
get:
summary: Lookup Account's Billing Info
description: |+
Returns only the account's current billing information.
tags:
- billing-info
operationId: lookupAccountsBillingInfo
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
VerenaExample123 Main St.San FranciscoCA94105US127.0.0.1truefalseVisa20191141111111112017-02-17T15:38:53Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find BillingInfo with account_code = 1
x-codeSamples:
- lang: PHP
source: |-
[PSD2](https://docs.recurly.com/docs/revised-payment-services-d\
irective-psd2) is a regulation from the EEA effective September 2019. It
requires 3DS / SCA (strong customer authentication) on certain
transactions. Recurly has updated our gateway integrations to support
this flow as well as enable merchants to send Recurly the required
parameters.\
This feature enables the fetching of ThreeDSecureActionToken and
the passing of a ThreeDSecureActionResultToken id through the API.
This change was made to facilitate the flow of information
needed to 3D secure a transaction for transactions requiring SCA.
Merchants with an acquiring bank in the EEA must comply with
SCA. They must support 3DS2 in order to authenticate card holders and
send authorizations for transactions that were subject to SCA.
\ "
tags:
- billing-info
operationId: createAccountsBillingInfoToken
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- token_id
properties:
token_id:
type: string
default: ""
description: A token [generated by
Recurly.js](https://recurly.com/developers/reference/recurly-js/#getting-a-token)
currency:
type: string
default: ""
description:
Currency in which invoices will be posted. Only applicable if this
account is enrolled in a plan has a different currency than
your site's default.
three_d_secure_action_result_token_id:
type: string
default: ""
description:
An id returned by Recurly.js referencing the result of the 3DS
authentication for
[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
transaction_type:
type: string
default: ""
description: 'Indicates type of resulting transaction. accepted_values: "moto".'
primary_payment_method:
type: boolean
default: false unless first billing info, then true for primary
description:
The `primary_payment_method` field is used to designate
the primary billing info on the account. The first billing info created
on an account will always become primary. Adding additional billing infos
provides the flexibility to mark another billing info as primary, or adding
additional non-primary billing infos. This can be accomplished by passing
the `primary_payment_method` field. When adding billing infos via
the billing_info and /accounts endpoints, this value is not permitted,
and will return an error if provided.
backup_payment_method:
type: boolean
default: false
description:
The `backup_payment_method` field is used to designate a
billing info as a backup on the account that will be tried if
initial billing_info used for the invoice fails. All payment methods,
including the billing info marked `primary_payment_method` can be set as a backup.
An account can have a maximum of 1 backup; if a user sets a different payment method
as a backup, the existing backup will no longer be marked as such.
responses:
"201":
description: ""
content:
application/xml:
example: >-
VerenaExample123 Main St.San FranciscoCA94105USUS1234567890127.0.0.1UStruefalseVisa20191141111111112017-02-17T15:38:53Z
"404":
description: ""
content:
application/xml:
example: |-
token_invalidToken is either invalid or expired
x-codeSamples:
- lang: xml
source: |-
TOKEN_ID
- lang: PHP
source: |-
account_code = 'b6f5783';
$billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js
$billing_info->create();
print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
// Could not find account or token is invalid or expired
print "Not Found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
account.billing_info = {
token_id: 'TOKEN_ID'
}
account.billing_info.save!
- lang: Python
source: |-
account = Account.get('1')
billing_info = account.billing_info
billing_info.token_id = 'TOKEN_ID'
account.update_billing_info(billing_info)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.TokenId = "TOKEN_ID";
info.Create();
put:
summary: Update Account's Billing Info (Token)
description:
"Updates an account's Billing Information using a token [generated
by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns
the account's current Billing Information.
[Recurly.js](https://js.recurly.com/) allows you to collect
customer Billing Information and tokenize it, preventing your servers
from having to handle credit card information. When you send these
tokens to Recurly through our API, we unpack the token and update
Billing Information accordingly.
When Billing Information is updated, it is only saved if valid.
If the account has a past due invoice, the outstanding balance will be
collected to validate the Billing Information.
If you want to create an account at the same time, you should
use the [Account API
end-point](https://docs.recurly.com/api/accounts#create-account) instead
and include billing info with your request.
###### PSD2 and 3DS Authentication
[PSD2](https://docs.recurly.com/docs/revised-payment-services-d\
irective-psd2) is a regulation from the EEA effective September 2019. It
requires 3DS / SCA (strong customer authentication) on certain
transactions. Recurly has updated our gateway integrations to support
this flow as well as enable merchants to send Recurly the required
parameters.\
This feature enables the fetching of ThreeDSecureActionToken and
the passing of a ThreeDSecureActionResultToken id through the API.
This change was made to facilitate the flow of information
needed to 3D secure a transaction for transactions requiring SCA.
Merchants with an acquiring bank in the EEA must comply with
SCA. They must support 3DS2 in order to authenticate card holders and
send authorizations for transactions that were subject to SCA.
\ "
tags:
- billing-info
operationId: updateAccountsBillingInfoToken
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- token_id
properties:
token_id:
type: string
default: ""
description: A token [generated by
Recurly.js](https://recurly.com/developers/reference/recurly-js/#getting-a-token).
currency:
type: string
default: ""
description:
Currency in which invoices will be posted. Only applicable if this
account is enrolled in a plan has a different currency than
your site's default.
three_d_secure_action_result_token_id:
type: string
default: ""
description:
An id returned by Recurly.js referencing the result of the 3DS
authentication for
[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
primary_payment_method:
type: boolean
description:
The `primary_payment_method` field is used to designate
the primary billing info on the account. The first billing info created
on an account will always become primary. Adding additional billing infos
provides the flexibility to mark another billing info as primary, or adding
additional non-primary billing infos. This can be accomplished by passing
the `primary_payment_method` field. When adding billing infos via
the billing_info and /accounts endpoints, this value is not permitted,
and will return an error if provided.
backup_payment_method:
type: boolean
description:
The `backup_payment_method` field is used to designate a
billing info as a backup on the account that will be tried if
initial billing_info used for the invoice fails. All payment methods,
including the billing info marked `primary_payment_method` can be set as a backup.
An account can have a maximum of 1 backup; if a user sets a different payment method
as a backup, the existing backup will no longer be marked as such.
responses:
"200":
description: ""
content:
application/xml:
example: >-
VerenaExample123 Main St.San FranciscoCA94105UStruefalseVisa20191141111111112017-02-17T15:38:53Z
"404":
description: ""
content:
application/xml:
example: |-
token_invalidToken is either invalid or expired
x-codeSamples:
- lang: xml
source: |-
TOKEN_ID
- lang: PHP
source: |-
account_code = 'b6f5783';
$billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js
$billing_info->update();
print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
// Could not find account or token is invalid or expired
print "Not Found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
account.billing_info.token_id = 'TOKEN_ID'
account.billing_info.save!
- lang: Python
source: |-
account = Account.get('1')
billing_info = account.billing_info
billing_info.token_id = 'TOKEN_ID'
account.update_billing_info(billing_info)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var info = new BillingInfo(account);
info.TokenId = "TOKEN_ID";
info.Update();
delete:
summary: Clear Account's Billing Info
description: >+
You may remove any stored billing information for an account. If the
account has a subscription, the renewal will go into past due unless you
update the billing info before the renewal occurs.
tags:
- billing-info
operationId: clearAccountsBillingInfo
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"204":
description: ""
content:
application/json:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
delete();
// Or, in a single API request:
// Recurly_BillingInfo::deleteForAccount('b6f5783');
print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
// Account not found or account does not have billing info
print "Not Found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
if billing_info = account.billing_info
billing_info.destroy
end
- lang: Python
source: |-
account = Account.get('1')
billing_info = account.billing_info
if billing_info
billing_info.delete()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
account.DeleteBillingInfo();
"/accounts/{account_code}/billing_info/verify":
post:
summary: Verify Account's Billing Info
description: |+
Validate account's credit card billing information.
tags:
- billing-info
operationId: verifyAccountsBillingInfo
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
gateway_code:
type: string
default: ""
description: An identifier for a specific payment gateway.
responses:
"200":
description: ""
content:
application/xml:
example: >-
3c429fe1aa71076aaf41524634816d53verify00USDdeclinedcredit_card6445370billing_infofalsetruefalsefalse127.0.0.1api_verify_cardAUTHORISED2017-03-15T21:16:52Z2017-03-15T21:16:52Z2017-03-15T21:16:52Zfalse1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019114000000341
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account
x-codeSamples:
- lang: PHP
source: >-
verify();
// verify with a specific gateway code
$billingInfo->verify($gateway_code="gateway-code");
} catch (Recurly_NotFoundError $e) {
// Could not find account or account
// doesn't have billing info
print "Not found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
billing_info = account.billing_info
# verify without specifying gateway code to use
billing_info.verify()
# verify with a specific gateway code
billing_info.verify({gateway-code: "gateway-code"})
- lang: Python
source: |-
account = Account.get('1')
billing_info = account.billing_info
billing_info.verify(account.account_code, 'gateway-code`) #account_code is a required param, gateway_code is optional
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var billingInfo = account.BillingInfo;
// verify without specifying gateway code to use
billingInfo.Verify()
// verify with a specific gateway code
billingInfo.Verify("gateway-code")
"/accounts/{account_code}/billing_info/verify_cvv":
post:
summary: Verify Account's Billing Info (Credit Card CVV)
description: |+
Validate account's credit card billing cvv.
tags:
- billing-info
operationId: verifyAccountsBillingInfoCVV
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
verification_value:
type: string
default: ""
description: Unique security code for a credit card.
responses:
"200":
description: ""
content:
application/xml:
example: >-
3c429fe1aa71076aaf41524634816d53verify00USDdeclinedcredit_card6445370billing_infofalsetruefalsefalse127.0.0.1api_verify_cardAUTHORISED2017-03-15T21:16:52Z2017-03-15T21:16:52Z2017-03-15T21:16:52Zfalse1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019114000000341
"422":
description: ""
content:
application/xml:
example: >-
fraud_security_codegeneric_declinefraudThe payment gateway declined the transaction because the security code (CVV) or expiration date did not match.The security code you entered does not match. Please update the CVV and try again.did not match
"400":
description: ""
content:
application/xml:
example: >-
cvv_verify_lockedThis credit card has too many cvv check attempts.
"/accounts/{account_code}/billing_infos":
get:
summary: List Account's Billing Infos
description: |+
When the wallet feature is enabled, an account may contain multiple billing informations.
Returns the account's multiple billing informations.
tags:
- billing-infos
operationId: lookupAccountsBillingInfos
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
iiznlrvdt05bVerenaExample123 Main St.San FranciscoCA94105US127.0.0.1Visa2019114111111111true2017-02-17T15:38:53Ziiznlrvdt8pyVerenaExample123 Main St.San FranciscoCA94105US127.0.0.1Visa2019114000111111false2017-02-17T15:38:53ZAcme, Inc.123 Main St.San FranciscoCA94105US127.0.0.1USchecking5555065400137false2017-02-17T15:38:53ZVerenaExample123 Main St.San FranciscoCA94105USBA-0HS87238YB688345Cfalse2017-02-17T15:38:53Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account
x-codeSamples:
- lang: PHP
source: |-
getBillingInfos();
- lang: Ruby
source: |-
account = Recurly::Account.find('accountCode')
account.get_billing_infos
- lang: Python
source: |-
account.Account.get('accountCode')
account.get_billing_infos()
- lang: Dotnet
source: |-
var account = Accounts.Get("accountCode");
var binfos = account.GetBillingInfos();
post:
summary: Create Account's Billing Info (Token)
description:
"Creates an account's Billing Information using a [token generated
by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns
the account's created Billing Information.
[Recurly.js](https://js.recurly.com/) allows you to collect
customer Billing Information and tokenize it, preventing your servers
from having to handle credit card information. When you send these
tokens to Recurly through our API, we unpack the token and update
Billing Information accordingly.
When Billing Information is updated, it is only saved if valid.
If the account has a past due invoice, the outstanding balance will be
collected to validate the Billing Information.
If you want to create an account at the same time, you should
use the [Account API
end-point](https://docs.recurly.com/api/accounts#create-account) instead
and include billing info with your request.
###### PSD2 and 3DS Authentication
[PSD2](https://docs.recurly.com/docs/revised-payment-services-d\
irective-psd2) is a regulation from the EEA effective September 2019. It
requires 3DS / SCA (strong customer authentication) on certain
transactions. Recurly has updated our gateway integrations to support
this flow as well as enable merchants to send Recurly the required
parameters.\
This feature enables the fetching of ThreeDSecureActionToken and
the passing of a ThreeDSecureActionResultToken id through the API.
This change was made to facilitate the flow of information
needed to 3D secure a transaction for transactions requiring SCA.
Merchants with an acquiring bank in the EEA must comply with
SCA. They must support 3DS2 in order to authenticate card holders and
send authorizations for transactions that were subject to SCA.
\ "
tags:
- billing-infos
operationId: createAccountsBillingInfoTokenWallet
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- token_id
properties:
token_id:
type: string
default: ""
description: A token [generated by
Recurly.js](https://recurly.com/developers/reference/recurly-js/#getting-a-token)
currency:
type: string
default: ""
description:
Currency in which invoices will be posted. Only applicable if this
account is enrolled in a plan has a different currency than
your site's default.
three_d_secure_action_result_token_id:
type: string
default: ""
description:
An id returned by Recurly.js referencing the result of the 3DS
authentication for
[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
transaction_type:
type: string
default: ""
description: 'Indicates type of resulting transaction. accepted_values: "moto".'
primary_payment_method:
type: boolean
default: false unless first billing info, then true for primary
description:
The `primary_payment_method` field is used to designate
the primary billing info on the account. The first billing info created
on an account will always become primary. Adding additional billing infos
provides the flexibility to mark another billing info as primary, or adding
additional non-primary billing infos. This can be accomplished by passing
the `primary_payment_method` field. When adding billing infos via
the billing_info and /accounts endpoints, this value is not permitted,
and will return an error if provided.
backup_payment_method:
type: boolean
default: false
description:
The `backup_payment_method` field is used to designate a
billing info as a backup on the account that will be tried if
initial billing_info used for the invoice fails. All payment methods,
including the billing info marked `primary_payment_method` can be set as a backup.
An account can have a maximum of 1 backup; if a user sets a different payment method
as a backup, the existing backup will no longer be marked as such.
responses:
"201":
description: ""
content:
application/xml:
example: >-
VerenaExample123 Main St.San FranciscoCA94105US4111-1111-1111-1111123112019127.0.0.13DS_TOKEN_IDtruetrue
"404":
description: ""
content:
application/xml:
example: |-
token_invalidToken is either invalid or expired
x-codeSamples:
- lang: xml
source: |-
TOKEN_ID
- lang: PHP
source: |-
token_id = '7z6furn4jvb9'; // From Recurly.js
$billing_info->backup_payment_method = true;
$account->createBillingInfo($billing_info);
} catch (Recurly_NotFoundError $e) {
// Could not find account or token is invalid or expired
print "Not Found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
billing_info = Recurly::BillingInfo.new(
token_id: 'TOKEN_ID',
backup_payment_method: true
)
account.create_billing_info(billing_info)
- lang: Python
source: |-
account = Account.get('1')
billing_info = recurly.BillingInfo(
token_id = 'TOKEN_ID',
backup_payment_method = True
)
account.create_billing_info(billing_info)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var info = new BillingInfo();
info.TokenId = "TOKEN_ID";
info.BackupPaymentMethod = true;
account.CreateBillingInfo(info);
"/accounts/{account_code}/billing_infos/{billing_info_uuid}":
get:
summary: Lookup Account's Billing Info
description: |+
Returns one of the account's billing informations
tags:
- billing-infos
operationId: lookupAccountsBillingInfoWallet
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code
- in: path
name: billing_info_uuid
schema:
type: string
default: ""
required: true
description: Billing info's uuid
responses:
"200":
description: ""
content:
application/xml:
example: >-
iiznlrvdt05bVerenaExample123 Main St.San FranciscoCA94105US127.0.0.1Visa2019114000111111truefalse2017-02-17T15:38:53Z
"400":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Billing Info with id iiznlrvdt05b
x-codeSamples:
- lang: PHP
source: |-
getBillingInfo("billing-info-uuid");
- lang: Ruby
source: |-
account = Recurly::Account.find('accountCode')
account.get_billing_info('billing-info-uuid')
- lang: Python
source: |-
account.Account.get('accountCode')
account.get_billing_info('billing-info-uuid')
- lang: Dotnet
source: |-
var account = Accounts.Get("accountCode");
var binfos = account.GetBillingInfo("billing-info-uuid");
put:
summary: Update Account's Billing Info (Token)
description:
"Updates an account's Billing Information using a token [generated
by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns
the account's current Billing Information.
[Recurly.js](https://js.recurly.com/) allows you to collect
customer Billing Information and tokenize it, preventing your servers
from having to handle credit card information. When you send these
tokens to Recurly through our API, we unpack the token and update
Billing Information accordingly.
When Billing Information is updated, it is only saved if valid.
If the account has a past due invoice, the outstanding balance will be
collected to validate the Billing Information.
If you want to create an account at the same time, you should
use the [Account API
end-point](https://docs.recurly.com/api/accounts#create-account) instead
and include billing info with your request.
###### PSD2 and 3DS Authentication
[PSD2](https://docs.recurly.com/docs/revised-payment-services-d\
irective-psd2) is a regulation from the EEA effective September 2019. It
requires 3DS / SCA (strong customer authentication) on certain
transactions. Recurly has updated our gateway integrations to support
this flow as well as enable merchants to send Recurly the required
parameters.\
This feature enables the fetching of ThreeDSecureActionToken and
the passing of a ThreeDSecureActionResultToken id through the API.
This change was made to facilitate the flow of information
needed to 3D secure a transaction for transactions requiring SCA.
Merchants with an acquiring bank in the EEA must comply with
SCA. They must support 3DS2 in order to authenticate card holders and
send authorizations for transactions that were subject to SCA.
\ "
tags:
- billing-infos
operationId: updateAccountsBillingInfoTokenWallet
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: path
name: billing_info_uuid
schema:
type: string
default: ""
required: true
description: Billing info's uuid
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- token_id
properties:
token_id:
type: string
default: ""
description: A token [generated by
Recurly.js](https://recurly.com/developers/reference/recurly-js/#getting-a-token).
currency:
type: string
default: ""
description:
Currency in which invoices will be posted. Only applicable if this
account is enrolled in a plan has a different currency than
your site's default.
three_d_secure_action_result_token_id:
type: string
default: ""
description:
An id returned by Recurly.js referencing the result of the 3DS
authentication for
[PSD2](https://docs.recurly.com/docs/revised-payment-services-directive-psd2)
primary_payment_method:
type: boolean
description:
The `primary_payment_method` field is used to designate
the primary billing info on the account. The first billing info created
on an account will always become primary. Adding additional billing infos
provides the flexibility to mark another billing info as primary, or adding
additional non-primary billing infos. This can be accomplished by passing
the `primary_payment_method` field. When adding billing infos via
the billing_info and /accounts endpoints, this value is not permitted,
and will return an error if provided.
backup_payment_method:
type: boolean
description:
The `backup_payment_method` field is used to designate a
billing info as a backup on the account that will be tried if
initial billing_info used for the invoice fails. All payment methods,
including the billing info marked `primary_payment_method` can be set as a backup.
An account can have a maximum of 1 backup; if a user sets a different payment method
as a backup, the existing backup will no longer be marked as such.
responses:
"200":
description: ""
content:
application/xml:
example: >-
VerenaExample123 Main St.San FranciscoCA94105USfalsetrueVisa20191141111111112017-02-17T15:38:53Z
"404":
description: ""
content:
application/xml:
example: |-
token_invalidToken is either invalid or expired
x-codeSamples:
- lang: xml
source: |-
TOKEN_IDfalsetrue
- lang: PHP
source: |-
getBillingInfo("billingInfoId");
$binfo_to_update->token_id = '7z6furn4jvb9'; // From Recurly.js
$binfo_to_update->primary_payment_method = false;
$binfo_to_update->backup_payment_method = true;
$billing_info = $account->updateBillingInfo($binfo_to_update);
print "Billing Info: $billing_info";
} catch (Recurly_NotFoundError $e) {
// Could not find account or token is invalid or expired
print "Not Found: $e";
}
- lang: Ruby
source: |-
binfo = account.get_billing_info('billing-info-uuid')
binfo.update_attributes(
token_id = 'TOKEN_ID',
primary_payment_method = false
backup_payment_method = true
)
- lang: Python
source: |-
binfo_to_update = account.get_billing_info('billingInfoUuid')
binfo_to_update.token_id = 'TOKEN_ID'
binfo_to_update.primary_payment_method = False
binfo_to_update.backup_payment_method = True
account.update_billing_info(binfo_to_update)
- lang: Dotnet
source: |-
var binfoToUpdate = account.GetBillingInfo("billingInfoUuid");
binfoToUpdate.TokenId = "TOKEN_ID";
binfoToUpdate.LastName = "Daytona";
binfoToUpdate.PrimaryPaymentMethod = false;
binfoToUpdate.BackupPaymentMethod = true;
account.UpdateBillingInfo(binfoToUpdate);
delete:
summary: Clear Account's Billing Info
description: >+
You may remove any stored billing information for an account. If the
account has a subscription, the renewal will go into past due unless you
update the billing info before the renewal occurs.
tags:
- billing-infos
operationId: clearAccountsBillingInfoWallet
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: path
name: billing_info_uuid
schema:
type: string
default: ""
required: true
description: Billing info's uuid
responses:
"204":
description: ""
content:
application/json:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
deleteBillingInfo("billingInfoId");
} catch (Recurly_NotFoundError $e) {
// Account not found or account does not have billing info
print "Not Found: $e";
}
- lang: Ruby
source: |-
binfo = account.get_billing_info('billing-info-uuid')
binfo.destroy
- lang: Python
source: |-
binfo = account.get_billing_info("billingInfoUuid")
binfo.delete()
- lang: Dotnet
source: |-
account.DeleteBillingInfo("billingInfoUuid");
"/accounts/{account_code}/shipping_addresses":
get:
summary: List Account's Shipping Address
description: |+
Returns a list of shipping addresses for an account.
tags:
- shipping-addresses
operationId: listAccountsShippingAddress
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2438622711411416831WorkVerenaExampleRecurly Incverena@example.com123 Main St.Suite 101San FranciscoCA94105US555-222-12122018-03-19T15:48:00Z2018-03-19T15:48:00Z2HomeVerenaExample555-867-5309verena@example.com123 Fourth St.Apt. 101San FranciscoCA94105US2016-06-14T16:08:42Z2016-06-14T16:08:42Z
x-codeSamples:
- lang: PHP
source: |-
-
# First get an account
account = Recurly::Account.find('1')
# Get all shipping addresses
shipping_addresses = account.shipping_addresses
# If you want to pass sorting/filtering params:
shipping_addresses = account.shipping_addresses.all(sort: :updated_at, order: :asc)
- lang: Python
source: |-
# first we need any account object
account = Account.get('1')
# the shipping_addresses method fetches the shipping addresses
# associated with this account
shipping_addresses = account.shipping_addresses()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var addresses = account.GetShippingAddresses();
post:
summary: Create Shipping Address
description: >+
Creates a new shipping address on an existing account.
Note: A shipping address can also be created via the [Create Account endpoint](https://recurly.com/developers/api-v2/latest/#operation/createAccount) as well as the [Create Subscription endpoint](https://recurly.com/developers/api-v2/latest/#operation/createSubscription). See the documentation for those endpoints to learn how to create a shipping address during account and subscription creation.
tags:
- shipping-addresses
operationId: createShippingAddress
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- first_name
- last_name
- address1
- city
- state
- zip
- country
properties:
nickname:
type: string
default: ""
description:
A nickname for the shipping address. Defaults to "first_name
last_name". Max of 255 characters.
first_name:
type: string
default: ""
description: The first name for the account. Max of 255 characters.
last_name:
type: string
default: ""
description: The last name for the account. Max of 255 characters.
company:
type: string
default: ""
description: The company name for the shipping address. Max of 50 characters.
phone:
type: string
default: ""
description: The phone number for the shipping address.
email:
type: string
default: ""
description: The email address for the shipping address.
address1:
type: string
default: ""
description: Address line 1.
address2:
type: string
default: ""
description: Address line 2.
city:
type: string
default: ""
description: City
state:
type: string
default: ""
description: State or region
zip:
type: string
default: ""
description: Zip or postal code
country:
type: string
default: ""
description: Country, [2-letter ISO
code](http://www.iso.org/iso/country_names_and_code_elements).
vat_number:
type: string
default: ""
description: Customer's VAT number (to avoid having VAT applied, if applicable).
responses:
"201":
description: ""
content:
application/xml:
example: >-
2438622711411416831WorkVerenaExampleRecurly Incverena@example.com123 Main St.Suite 101San FranciscoCA94105US555-222-12122018-03-19T15:48:00Z2018-03-19T15:48:00Z
x-codeSamples:
- lang: xml
source: |-
WorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101San FranciscoCA94105US
- lang: PHP
source: |-
nickname = "Work";
$shipping_address->first_name = "Verena";
$shipping_address->last_name = "Example";
$shipping_address->company = "Recurly Inc.";
$shipping_address->phone = "555-555-5555";
$shipping_address->email = "verena@example.com";
$shipping_address->address1 = "123 Main St.";
$shipping_address->city = "San Francisco";
$shipping_address->state = "CA";
$shipping_address->zip = "94110";
$shipping_address->country = "US";
// Persist the shipping address and link to the account
$account->createShippingAddress($shipping_address);
- lang: Ruby
source: |
# Shipping addresses can be created in 3 ways:
# 1. Embed 1 to many shipping address on an account creation
# 2. Embed 1 shipping address on subscription creation
# 3. Create a shipping address on an existing account
# For 1 and 2, see account and subscription creation respectively
# This code example shows case #3
# Fetch an existing account
account = Recurly::Account.find('1')
# Call create on the shipping_addresses association
shipping_address = account.shipping_addresses.create(
nickname: "Work",
first_name: "Verena",
last_name: "Example",
company: "Recurly Inc.",
phone: "555-555-5555",
email: "verena@example.com",
address1: "400 Alabama St.",
city: "San Francisco",
state: "CA",
zip: "94110",
country: "US"
)
- lang: Python
source: |-
# Shipping addresses can be created in 3 ways:
# 1. Embed 1 to many shipping address on an account creation
# 2. Embed 1 shipping address on subscription creation
# 3. Create a shipping address on an existing account
# For 1 and 2, see account and subscription creation respectively
# This code example shows case #3
# First find an existing account
account = Account.get('1')
# Create your shipping address object
shad = ShippingAddress()
shad.nickname = "Work"
shad.first_name = "Verena"
shad.last_name = "Example"
shad.company = "Recurly Inc."
shad.phone = "555-555-5555"
shad.email = "verena@example.com"
shad.address1 = "123 Main St."
shad.city = "San Francisco"
shad.state = "CA"
shad.zip = "94110"
shad.country = "US"
# Persist the shipping address and link to the account
account.create_shipping_address(shad)
- lang: Dotnet
source: |-
// Shipping addresses can be created in 3 ways:
// 1. Embed 1 to many shipping address on an account creation
// 2. Embed 1 shipping address on subscription creation
// 3. Create a shipping address on an existing account
// For 1 and 2, see account and subscription creation respectively
// This code example shows case #3
// First find an existing account
var account = Accounts.Get("1");
// Create your shipping address object
var newAddress = new ShippingAddress();
newAddress.FirstName = "Verena";
newAddress.LastName = "Example";
newAddress.Email = "verena@example.com";
newAddress.Address1 = "123 Main St.";
newAddress.Address2 = "Suite 101";
newAddress.City = "San Francisco";
newAddress.State = "CA";
newAddress.Country = "US";
newAddress.Zip = "94105";
// Persist the shipping address and link to the account
var shippingAddress = account.CreateShippingAddress(newAddress);
"/accounts/{account_code}/shipping_addresses/{shipping_address_id}":
put:
summary: Update Shipping Address
description: |+
Updates an existing shipping address on an existing account.
tags:
- shipping-addresses
operationId: updateShippingAddress
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
- in: path
name: shipping_address_id
schema:
type: string
default: ""
required: true
description: Shipping address unique identifier.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
nickname:
type: string
default: ""
description:
A nickname for the shipping address. Defaults to "first_name
last_name". Max of 255 characters.
first_name:
type: string
default: ""
description: The first name for the account. Max of 255 characters.
last_name:
type: string
default: ""
description: The last name for the account. Max of 255 characters.
company:
type: string
default: ""
description: The company name for the account. Max of 50 characters.
phone:
type: string
default: ""
description: The phone number for the shipping address.
email:
type: string
default: ""
description: The email address for the account.
address1:
type: string
default: ""
description: Address line 1.
address2:
type: string
default: ""
description: Address line 2.
city:
type: string
default: ""
description: City
state:
type: string
default: ""
description: State or region
zip:
type: string
default: ""
description: Zip or postal code
country:
type: string
default: ""
description: Country, [2-letter ISO
code](http://www.iso.org/iso/country_names_and_code_elements).
vat_number:
type: string
default: ""
description: The VAT number to avoid having the VAT applied (if applicable).
responses:
"201":
description: ""
content:
application/xml:
example: >-
2438622711411416831Verena ExampleVerenaExampleRecurly Incverena@example.com123 Main St.San FranciscoCA94105US555-222-12342018-03-19T15:48:00Z2018-03-19T15:51:15Z
x-codeSamples:
- lang: xml
source: |-
newnickname555-222-1234
- lang: PHP
source: |-
nickname = 'newnickname';
$shipping_address->phone = '555-222-1234';
$shipping_address->update();
- lang: Ruby
source: |-
# Call update_attributes on any shipping_address object
shipping_address.update_attributes(
nickname: 'newnickname',
phone: '555-222-1234'
)
- lang: Python
source: |-
# mutate the properties of any shipping address object
shipping_address.nickname = 'newnickname'
shipping_address.phone = '555-222-1234'
# then call save
shipping_address.save()
- lang: Dotnet
source: >-
var account = Accounts.Get("1");
var shippingAddress = account.GetShippingAddresses().First();
shippingAddress.Nickname = "newnickname";
shippingAddress.Phone = "555-222-1234";
var updatedShippingAddress = account.UpdateShippingAddress(shippingAddress);
delete:
summary: Delete Shipping Address
description: |+
Deletes an existing shipping address from an existing account.
tags:
- shipping-addresses
operationId: deleteShippingAddress
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
- in: path
name: shipping_address_id
schema:
type: string
default: ""
required: true
description: Shipping address unique identifier.
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: Ruby
source: |-
# call destroy on any shipping address object
shipping_address.destroy
- lang: Python
source: |-
# call delete() on any shipping address object
shipping_address.delete()
- lang: Dotnet
source: |-
var account = Accounts.Get("x");
var shippingAddress = account.GetShippingAddresses().First();
var id = shippingAddress.Id;
account.DeleteShippingAddress((long) id);
"/accounts/{account_code}/acquisition":
post:
summary: Create Account Acquisition
description: |+
Create or update an account's acquisition data.
tags:
- account-acquisition
operationId: createAccountAcquisition
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
cost_in_cents:
type: integer
default: ""
description: Total cost of marketing activities to acquire the customer.
currency:
type: string
default: ""
description: Currency, 3-letter ISO code.
channel:
type: string
default: ""
description:
"The method by which the customer was acquired. Allowed values:
`referral`, `social_media`, `email`, `paid_search`,
`organic_search`, `direct_traffic`, `marketing_content`,
`blog`, `events`, `outbound_sales`, `advertising`,
`public_relations`, `other`."
subchannel:
type: string
default: ""
description:
A free-form field to provide additional detail on the acquisition
channel.
campaign:
type: string
default: ""
description: Identifier for the marketing campaign used to convert this account.
responses:
"200":
description: ""
content:
application/xml:
example: >-
199USDblogWhitepaper Blog Postmailchimp67a904de95.0914d8f4b42016-08-12T19:45:14Z2016-08-12T19:45:14Z
"400":
description: ""
content:
application/json:
example: "{}"
x-codeSamples:
- lang: xml
source: |-
199USDblogWhitepaper Blog Postmailchimp67a904de95.0914d8f4b4
- lang: PHP
source: |-
account_code = '1';
$acquisition->cost_in_cents = 142;
$acquisition->currency = 'USD';
$acquisition->channel = 'paid_search';
$acquisition->subchannel = 'Google Ads';
$acquisition->campaign = 'JSE-2345';
$acquisition->create();
- lang: Ruby
source: |-
account = Recurly::Account.find '1'
account.account_acquisition = {
cost_in_cents: 199,
currency: "USD",
channel: "blog",
subchannel: "Whitepaper Blog Post",
campaign: "mailchimp67a904de95.0914d8f4b4"
}
account.save
- lang: Python
source: |-
account = recurly.Account.get('1')
acquisition = recurly.AccountAcquisition()
acquisition.cost_in_cents = 199
acquisition.currency = 'USD'
acquisition.channel = 'blog'
acquisition.subchannel = 'Whitepaper Blog Post'
acquisition.campaign = 'mailchimp67a904de95.0914d8f4b4'
account.account_acquisition = acquisition
account.save()
- lang: Dotnet
source: |-
var accountAcq = new AccountAcquisition("account-code");
accountAcq.CostInCents = 100;
accountAcq.Currency = "USD";
accountAcq.Channel = AccountAcquisition.AccountAcquisitionChannel.SocialMedia;
accountAcq.Create();
get:
summary: Lookup Account Acquisition
description: |+
Returns an account's acquisition data.
tags:
- account-acquisition
operationId: lookupAccountAcquisition
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
199USDblogWhitepaper Blog Postmailchimp67a904de95.0914d8f4b42016-08-12T19:45:14Z2016-08-12T19:45:14Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find AccountAcquisition with account_code = 1
x-codeSamples:
- lang: PHP
source: |-
-
150EURblogWhitepaper Blog Postmailchimp67a904de95.0914d8f4b42016-08-12T19:49:43Z2016-08-12T19:49:55Z
"400":
description: ""
content:
application/json:
example: "{}"
x-codeSamples:
- lang: xml
source: |-
150EUR
- lang: PHP
source: |-
currency = 'EUR';
$acquisition->cost_in_cents = 150;
$acquisition->update();
- lang: Ruby
source: |-
account = Recurly::Account.find '1'
account.account_acquisition = {
cost_in_cents: 200
}
account.save!
- lang: Python
source: |-
account = recurly.Account.get('1')
acquisition = account.account_acquisition()
acquisition.cost_in_cents = 150
acquisition.currency = 'EUR'
acquisition.save()
- lang: Dotnet
source: |-
var acquisition = AccountAcquisition.Get("1");
acquisition.CostInCents = 200;
acquisition.Update();
delete:
summary: Clear Account Acquisition
description: |+
Remove an account's acquisition data.
tags:
- account-acquisition
operationId: clearAccountAcquisition
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
responses:
"204":
description: ""
content:
application/xml:
example: ""
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find AccountAcquisition with account_code = 1
x-codeSamples:
- lang: PHP
source: |-
-
smygx37luhzxe54f884c-59d7-44e4-9bf2-752ea0d8f268AppleAppStore2023-04-03T15:44:05Z2023-04-03T15:44:05Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: PHP
source: |-
getExternalAccounts();
foreach ($external_accounts as $external_account) {
print "ExternalAccount: $external_account\n";
}
} catch (Recurly_NotFoundError $e) {
print "Invalid account code: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
account.external_accounts.find_each do |external_account|
puts "ExternalAccount: #{external_account.inspect}"
end
- lang: Python
source: |-
account = Account.get('1')
for external_account in account.external_accounts():
print 'ExternalAccount: %s' % external_account
- lang: Dotnet
source: |-
var account = Helpers.CreateAccount();
account.CreateExternalAccount(new ExternalAccount(){
ExternalAccountCode = "external_account_code",
ExternalConnectionType = "GooglePlayStore"
});
var externalAccounts = account.GetExternalAccounts();
while (externalAccounts.Any())
{
foreach (var externalAccount in externalAccounts) {
Console.WriteLine("External Account Id: " + externalAccount.Id);
Console.WriteLine("External Account ExternalAccountCode: " + externalAccount.ExternalAccountCode);
Console.WriteLine("External Account ExternalConnectionType: " + externalAccount.ExternalConnectionType);
Console.WriteLine("External Account CreatedAt: " + externalAccount.CreatedAt);
Console.WriteLine("External Account UpdatedAt: " + externalAccount.UpdatedAt);
}
externalAccounts = externalAccounts.Next;
}
post:
summary: Creates an External Account for an Account
description: Creates an External Account for an Account
tags:
- external-accounts
operationId: createAccountExternalAccounts
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- external_account_code
- external_connection_type
properties:
external_account_code:
type: string
default: ""
description: Represents the account code for the external account.
external_connection_type:
type: string
default: ""
description: Represents the connection type. `AppleAppStore` or `GooglePlayStore`
responses:
"201":
description: ""
content:
application/xml:
example: >-
snce78zq4j61stringAppleAppStore2023-04-03T15:44:05Z2023-04-03T15:44:05Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: xml
source: >-
account-codeOtherFruitAppStore
- lang: PHP
source: >-
external_account_code = 'account-code';
$external_account_info->external_connection_type = 'AppleAppStore';
$account->createExternalAccount($external_account_info);
} catch (Recurly_ValidationError $e) {
// The data are invalid
print "Invalid data: $e";
} catch (Recurly_NotFoundError $e) {
// Could not find account
print "Not Found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
external_account_info = (
{
external_account_code: 'account-code',
external_connection_type: 'GooglePlayStore',
}
)
account.external_accounts.create!(external_account_info)
- lang: Python
source: |-
account = Account.get('1')
external_account_info = recurly.ExternalAccount(
external_account_code = 'account-code'
external_connection_type = 'AppleAppStore'
)
account.create_external_account(external_account_info)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var info = new ExternalAccount();
info.ExternalAccountCode = "account-code";
info.ExternalConnectionType = "AppleAppStore";
account.CreateExternalAccount(info);
"/accounts/{account_code}/external_accounts/{external_account_uuid}":
get:
summary: Fetch an Account's External Account
description: ""
tags:
- external-accounts
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: path
name: external_account_uuid
schema:
type: string
default: ""
required: true
description: External Account's unique id.
operationId: fetchAccountExternalAccount
responses:
"200":
description: ""
content:
application/xml:
example: >-
smygx37luhzxe54f884c-59d7-44e4-9bf2-752ea0d8f268AppleAppStore2023-04-03T15:44:05Z2023-04-03T15:44:05Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: PHP
source: |-
getExternalAccount('external_account_uuid');
print "External Account: $external_account\n";
} catch (Recurly_NotFoundError $e) {
print "External Account does not exist";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
account.external_accounts.find('2')
- lang: Python
source: |-
account = Account.get('1')
external_account = account.external_accounts().get('p7gnbhfxbe8o')
- lang: Dotnet
source: |-
using System.Linq;
var account = Accounts.Get("1");
var external_account = account.GetExternalAccounts().Get("p7gnbhfxbe8o");
put:
summary: Updates an External Account for an Account
description: Updates an External Account for an Account
tags:
- external-accounts
operationId: udpateAccountExternalAccount
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: path
name: external_account_uuid
schema:
type: string
default: ""
required: true
description: External Account's unique id.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
external_account_code:
type: string
default: ""
description: Represents the account code for the external account.
external_connection_type:
type: string
default: ""
description: Represents the connection type. `AppleAppStore` or `GooglePlayStore`
responses:
"200":
description: ""
content:
application/xml:
example: >-
snce78zq4j61stringAppleAppStore2023-04-03T15:44:05Z2023-04-04T15:44:05Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: xml
source: |-
f3b5f8ce-34ae-4a95-8f26-fbfc2d9b28b7AppleAppStore
- lang: PHP
source: |-
getExternalAccount("externalAccountId");
$external_account->external_account_code = 'f3b5f8ce-34ae-4a95-8f26-fbfc2d9b28b7';
$external_account->external_connection_type = 'AppleAppStore';
$external_account->update();
print "ExternalAccount $external_account->external_account_code updated";
} catch (Recurly_ValidationError $e) {
// The data is invalid
print "Invalid data: $e";
} catch (Recurly_NotFoundError $e) {
// Could not find account
print "Account Not Found: $e";
}
- lang: Ruby
source: |-
external_account = account.external_accounts.find('external-account-uuid')
external_account.external_account_code = '1234'
external_account.save!
- lang: Python
source: |-
external_account = account.get_external_account('externalAccountUuid')
external_account.external_account_code = 'f3b5f8ce-34ae-4a95-8f26-fbfc2d9b28b7'
external_account.external_connection_type = 'AppleAppStore'
external_account.save()
- lang: Dotnet
source: |-
var externalAccount = account.GetExternalAccount("externalAccountUuid");
externalAccount.ExternalAccountCode = "f3b5f8ce-34ae-4a95-8f26-fbfc2d9b28b7";
externalAccount.ExternalConnectionType = "AppleAppStore";
account.UpdateExternalAccount(externalAccount);
delete:
summary: Delete External Account Record
description: Delete an External Account on your account.
tags:
- external-accounts
operationId: deleteAccountExternalAccount
parameters:
- in: path
name: account_code
schema:
type: string
required: true
description: Account unique identifier.
- in: path
name: external_account_uuid
schema:
type: string
required: true
description: The unique External Account UUID.
responses:
"204":
description: ""
content:
application/json:
example: "Status: 204 No Content"
"404":
description: External Account not found
content:
application/xml:
example: >-
not_foundCouldn't find ExternalAccount with id snxskxf3tn4q
"400":
description: Unavailable API version
content:
application/xml:
examples:
unavailable_api_version:
summary: Unavailable API version
value: >-
unavailable_in_api_versionThis request cannot be completed using this version of the API. It was added in version '2.29'.
feature_not_enabled:
summary: Feature not enabled
value: >-
feature_not_enabledExternal Resource Tracking feature is not enabled for your site
x-codeSamples:
- lang: PHP
source: |-
getExternalAccount('external_account_uuid');
$external_account->delete();
} catch (Recurly_NotFoundError $e) {
// Account not found or account does not have external account
print "Not Found: $e";
}
- lang: Ruby
source: |-
external_account = account.external_accounts.find('external-account-uuid')
external_account.destroy
- lang: Python
source: |-
external_account = account.get_external_account("externalAccountUuid")
external_account.delete()
- lang: Dotnet
source: |-
account.DeleteExternalAccount("externalAccountUuid");
"/adjustments/{adjustment_uuid}":
get:
summary: Lookup Adjustment
description: >+
The history of your customer's Recurly account can be tracked through
adjustments, made up of credits and charges.
tags:
- adjustments
operationId: lookupAdjustment
parameters:
- in: path
name: adjustment_uuid
schema:
type: string
required: true
description: Adjustment's unique uuid.
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Adjustment"
example: >-
37bff9dd3ec90471cf62bd4f6f80db3dinvoicedRefund for Setup fee: Gold plangoldsetup_fee800-1037bfef7af3cd23ee89d77a435aa1838d0-70-870EUR0.1falseusstCA0.0875origindestinationfalsestate0.065-52county0.01-8city0.00special0.0125-102016-08-03T16:02:24Z2016-08-03T16:13:44Z2016-08-03T16:13:44Zevenly
x-codeSamples:
- lang: PHP
source: |-
performance_obligation_id\n";
print "revenue_gl_account_code: $adjustment->revenue_gl_account_code\n";
print "liability_gl_account_code: $adjustment->liability_gl_account_code\n";
} catch (Recurly_NotFoundError $e) {
print "Adjustment not found";
}
- lang: Ruby
source: |-
adjustment = Recurly::Adjustment.find('5741d61fd2ba2a39c3214f4b98ac4543')
# Recurly RevRec Standard/Advanced (RA-Managed)
# general ledger account (gla) IDs passed on creation but
# only the codes attached to record
puts "performance_obligation_id: #{adjustment.performance_obligation_id}\n"
puts "revenue_gl_account_code: #{adjustment.revenue_gl_account_code}\n"
puts "liability_gl_account_code: #{adjustment.liability_gl_account_code}\n"
- lang: Python
source: |-
adjustment = Adjustment.get('5741d61fd2ba2a39c3214f4b98ac4543')
# Recurly RevRec Standard/Advanced (RA-Managed)
# general ledger account (gla) IDs passed on creation but
# only the codes attached to record
print(f'PerformanceObligationId: {adjustment.performance_obligation_id}')
print(f'LiabilityGlAccountCode: {adjustment.liability_gl_account_code}')
print(f'RevenueGlAccountCode: {adjustment.revenue_gl_account_code}')
- lang: Dotnet
source: |-
var adjustment = Adjustments.Get("5741d61fd2ba2a39c3214f4b98ac4543");
// Recurly RevRec Standard/Advanced (RA-Managed)
// general ledger account (gla) IDs passed on creation but
// only the codes attached to record
System.Console.WriteLine("PerformanceObligationId: " + adjustment.PerformanceObligationId);
System.Console.WriteLine("LiabilityGlAccountCode: " + adjustment.LiabilityGlAccountCode);
System.Console.WriteLine("RevenueGlAccountCode: " + adjustment.RevenueGlAccountCode);
- lang: Java
source: |-
final Adjustment adjustment = Adjustment.get(adjustmentId);
System.out.println("Adjustment: " + adjustment);
// Recurly RevRec Standard/Advanced (RA-Managed)
// general ledger account (gla) IDs passed on creation but
// only the codes attached to record
System.out.println("PerformanceObligationId: " + adjustment.getPerformanceObligationId());
System.out.println("LiabilityGlAccountCode: " + adjustment.getLiabilityGlAccountCode());
System.out.println("RevenueGlAccountCode: " + adjustment.getRevenueGlAccountCode());
delete:
summary: Delete Adjustment
description: "Delete an adjustment from an account. Only non-invoiced
adjustments can be deleted.
###### Please note
An adjustment may only be deleted if it has not been invoiced.
\ "
tags:
- adjustments
operationId: deleteAdjustment
parameters:
- in: path
name: adjustment_uuid
schema:
type: string
default: ""
required: true
description: The unique identifier for the adjustment
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: >
delete();
print "Adjustment: $adjustment";
} catch (Recurly_NotFoundError $e) {
// NotFoundError if invalid uuid or already deleted
print "Invalid adjustment uuid: $e";
}
- lang: Ruby
source: >-
adjustment =
Recurly::Adjustment.find('945a4cb9afd64300b97b138407a51aef')
adjustment.destroy
- lang: Python
source: |-
adjustment = Adjustment.get('945a4cb9afd64300b97b138407a51aef')
adjustment.delete()
- lang: Dotnet
source: >-
var adjustment =
Adjustments.Get("945a4cb9afd64300b97b138407a51aef");
adjustment.Delete(
"/adjustments/{adjustment_uuid}/credit_adjustments":
parameters:
- in: path
name: adjustment_uuid
schema:
type: string
default: ""
required: true
description: Charge Adjustment's unique uuid
get:
summary: List Credit Adjustments for Charge Adjustment
description: "Given a charge adjustment, returns a list of credit adjustments that were issued against it"
tags:
- adjustments
operationId: listCreditAdjustments
responses:
"200":
description: ""
content:
application/xml:
schema:
type: array
items:
$ref: "#/components/schemas/Adjustment"
example: >-
57d7416d375d461859c4db45c28ceca8invoicedChargedebit-941157d73e27ccf5acf411d12a47969903280-6-100USDusstMI0.06false2020-12-15T00:00:00Z2020-12-15T22:12:24Z2020-12-15T22:12:24Zat_range_startrefundsizelarge
x-codeSamples:
- lang: PHP
source: |-
credit_adjustments->get();
foreach ($credit_adjustments as $credit_adjustment) {
print "Credit Adjustment: $credit_adjustment\n";
}
} catch (Recurly_NotFoundError $e) {
print "Invalid charge adjustment uuid: $e";
}
- lang: Ruby
source: |-
charge_adjustment = Recurly::Adjustment.find('57d73e27ccf5acf411d12a4796990328')
charge_adjustment.credit_adjustments.find_each do |credit_adjustment|
puts "Credit Adjustment: #{credit_adjustment.inspect}"
end
- lang: Python
source: |-
charge_adjustment = Adjustment.get('57d73e27ccf5acf411d12a4796990328')
for credit_adjustment in charge_adjustment.credit_adjustments():
print 'Credit Adjustment: %s' % credit_adjustment
"/accounts/{account_code}/adjustments":
get:
summary: List Account's Adjustments
description: >+
Returns a list of adjustments for a given account. Results are ordered
by the time created, sorted by newest first.
tags:
- adjustments
operationId: listAccountsAdjustments
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: type
schema:
type: string
default: ""
description: "The type of adjustment to filter by. Allowed values:
[`charge`, `credit`]"
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of the adjustment to filter by. Allowed Values:
[`invoice`, `pending`]"
responses:
"200":
description: ""
content:
application/xml:
schema:
type: array
items:
$ref: "#/components/schemas/Adjustment"
example: >-
43adb610c8709fb70e6297427eaef17apendingBonus for being a great customercredit-2000100-2000USDfalsefalse2018-03-19T15:39:59Z2018-03-19T15:39:59Z2018-03-19T15:39:59Zat_invoicesizelarge
x-codeSamples:
- lang: PHP
source: |-
Unless you need to separately create adjustments and invoice
them later, prefer the Purchases instead and
invoice them immediately, including the collection of a successful
transaction for any balance.
\ "
tags:
- adjustments
operationId: createCharge
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- currency
- unit_amount_in_cents
properties:
currency:
type: string
default: ""
description: Currency, 3-letter ISO code.
unit_amount_in_cents:
type: string
default: ""
description:
Positive amount for a charge, negative amount for a credit. Max
10000000.
tax_inclusive:
$ref: "#/components/schemas/TaxInclusive"
quantity:
type: integer
default: "1"
description: Quantity.
description:
type: string
default: ""
description: Description of the adjustment for the invoice.
accounting_code:
type: string
default: ""
description: Accounting code. Max of 20 characters.
revenue_schedule_type:
type: string
default: ""
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Charge should be
recognized. Available schedule types are `never`,
`at_range_start`, `at_invoice`, and—if `end_date` is
set—`evenly` and `at_range_end`.
tax_exempt:
type: boolean
default: ""
description:
"`true` exempts tax on the charge, `false` applies tax on the
charge. If not defined, then defaults to the Plan and Site
settings. This attribute does not work for credits (negative
adjustments). Credits are always post-tax. Pre-tax discounts
should use the Coupons feature."
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box
tax solution to determine taxation rules. You can pass in specific tax codes
using any of these tax integrations. For Recurly's In-the-Box tax offering
you can also choose to instead use simple values of `unknown`, `physical`, or
`digital` tax codes.
start_date:
type: string
format: date-time
default: now
description: A timestamp associated with when the charge began.
end_date:
type: string
format: date-time
default: ""
description: A timestamp associated with when the charge ended.
product_code:
type: string
default: ""
description:
The product code or SKU of the line item. Max of 50 characters.
Useful for later reporting on product purchases.
item_code:
type: string
default: ""
description:
The `item_code` for the item associated with the adjustment, if
there is one. Associates the adjustment with an item and
sets related attributes on the adjustment from the default
values on the item. ``, ``,
``, `` and `` are not
accepted when `` is present.
vertex_transaction_type:
"$ref": "#/components/schemas/VertexTransactionTypeEnum"
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
origin_tax_address_source:
"$ref": "#/components/schemas/OriginTaxAddressSourceEnum"
destination_tax_address_source:
"$ref": "#/components/schemas/DestinationTaxAddressSourceEnum"
responses:
"201":
description: ""
content:
application/xml:
example: >-
cool_beans43adb5a639dc950ff620de42e6be4141pendingCharge for extra bandwidthbandwidthdebit50001005000USDfalsefalse2018-03-19T15:39:31Z2018-03-19T15:39:31Z2018-03-19T15:39:31Zat_invoicesalefirst_liabilityfirst_revenue7pssizelarge
schema:
$ref: "#/components/schemas/Adjustment"
x-codeSamples:
- lang: xml
source: |-
5000USD1at_invoicecool_beanssalety4utwr0mrgztwyyzw8vcm367pssizelarge
- lang: PHP
source: |-
account_code = 'b6f5783';
$charge->unit_amount_in_cents = 5000; // $50.00
$charge->currency = 'USD';
$charge->quantity = 1;
$charge->item_code = 'cool_beans';
$charge->custom_fields[] = new Recurly_CustomField('size', 'large');
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
$charge->performance_obligation_id = $my_pob_id;
// [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$charge->revenue_gl_account_id = $my_revenue_gla_id;
$charge->liability_gl_account_id = $my_liability_gla_id;
$charge->create();
print "Charge: $charge";
} catch (Recurly_NotFoundError $e) {
print "Account not found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
account.adjustments.create(
:unit_amount_in_cents => 50_00,
:currency => 'USD',
:quantity => 1,
:item_code => 'cool_beans',
:custom_fields => [Recurly::CustomField.new(name: 'size', value: 'large')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
performance_obligation_id: pob_id,
# [liability|revenue]_gl_account_id will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
revenue_gl_account_id: revenue_gla_id,
liability_gl_account_id: liability_gla_id,
)
- lang: Python
source: |-
account = Account.get('1')
charge = Adjustment(
unit_amount_in_cents=5000,
currency='USD',
quantity=1,
item_code='cool_beans',
custom_fields=[recurly.CustomField(name = 'size', value = 'large')]
)
# Recurly RevRec Standard/Advanced (RA-Managed)
# PerformanceObligationId will be set to the default if omitted,
# but can be explicitly set if desired.
charge.performance_obligation_id = performance_obligation_id
# will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
charge.liability_gl_account_id = liability_gl_account_id
charge.revenue_gl_account_id = revenue_gl_account_id
account.charge(charge)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var adjustment = account.NewAdjustment("USD", 5000);
adjustment.ItemCode = 'cool_beans';
adjustment.RevenueScheduleType = Adjustment.RevenueSchedule.AtInvoice;
adjustment.CustomFields.Add(new CustomField("size", "large"));
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
adjustment.PerformanceObligationId = myPobId;
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
adjustment.LiabilityGlAccountId = myLiabilityGlaId;
adjustment.RevenueGlAccountId = myRevenueGlaId;
adjustment.Create();
- lang: Java
source: |-
final Adjustment adjustment = new Adjustment();
adjustment.setUnitAmountInCents(350);
adjustment.setCurrency("USD");
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
adjustment.setPerformanceObligationId(pobId);
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
adjustment.setLiabilityGlAccountId(liabilityGlaId);
adjustment.setRevenueGlAccountId(revenueGlaId);
final Adjustment adj = client.createAccountAdjustment(account.getAccountCode(), adjustment);
"/coupons":
get:
summary: List Coupons
description: |+
Returns a list of all the coupons.
tags:
- coupons
operationId: listCoupons
parameters:
- in: query
name: state
schema:
type: string
default: all
description: "The state of coupons to return: `redeemable`, `expired`,
or `maxed_out`."
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2151093486799579392specialSpecial 10% offredeemablepercent102017-12-31T00:00:00Ztrue200false2016-07-11T18:50:17Z2016-07-11T18:50:17Zsingle_usefalseaccountsingle_codegoldplatinum
x-codeSamples:
- lang: PHP
source: |-
-
Creates a new coupon. Please note: coupons cannot be updated after being
created.
**DISCOUNT IN DOLLARS**
When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:
```xml
dollars500400300
```
**DISCOUNT IN PERCENTAGE**
Percentage discounts only need to specify the discount percentage. For example:
```xml
percent10
```
**LIMITING TO SPECIFIC PLANS**
If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:
```xml
falsesilvergold
```
**LIMITING TO SPECIFIC ITEMS**
To limit a coupon to specific items, you may specify an array of item codes. For example:
```xml
falseterracottaterrazzomarble
```
**CREATING UNIQUE CODE TEMPLATES**
If you are creating a bulk coupon, you will need to create a unique_code_template. Here are the rules:
1. You must start the template with your coupon_code wrapped in single quotes.
2. Outside of single quotes, use a 9 for a character that you want to be a random number.
3. Outside of single quotes, use an "x" for a character that you want to be a random letter.
4. Outside of single quotes, use an * for a character that you want to be a random number or letter.
5. Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.
```xml
thankyoubulk'thankyou'99999999
```
This example will create a unique code like: thankyou41863675
tags:
- coupons
operationId: createCoupon
parameters: []
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- coupon_code
- name
- discount_type
properties:
coupon_code:
type: string
default: ""
description:
"Unique code to identify and redeem the coupon. This code may only
contain the following characters: [a-z A-Z 0-9 + - _ ]. Max
of 50 characters."
name:
type: string
default: ""
description: Coupon name.
description:
type: string
default: ""
description: Description of the coupon on the hosted payment pages.
discount_type:
type: string
default: ""
description: "`percent`, `dollars`, or `free_trial`."
discount_in_cents:
type: integer
default: ""
description:
Mapping of discount amounts by currency if discount_type is
`dollars`. Max 10000000.
discount_percent:
type: integer
default: ""
description: Discount percentage if discount_type is `percent`.
invoice_description:
type: string
default: ""
description: Description of the coupon on the invoice.
redeem_by_date:
type: string
format: date-time
default: ""
description: Last date to redeem the coupon, defaults to no date.
single_use:
type: boolean
default: ""
description:
"DEPRECATED: Please use `duration`. If true, the coupon applies to
the first invoice only."
applies_for_months:
type: integer
default: ""
description:
"DEPRECATED: Please use `temporal_unit` and `temporal_amount`.
Number of months after redemption that the coupon is valid,
defaults to no date."
max_redemptions:
type: integer
default: ""
description:
Maximum number of accounts that may use the coupon before it can no
longer be redeemed.
applies_to_all_plans:
type: boolean
default: "true"
description: The coupon is valid for all plans if true, defaults to true.
applies_to_all_items:
type: boolean
default: "false"
description: The coupon is valid for all items if true, defaults to false.
duration:
type: string
default: forever
description:
"`forever`, `single_use`, or `temporal`. If `single_use`, the
coupon applies to the first invoice only. If `temporal` the
coupon will apply to invoices for the duration determined by
the `temporal_unit` and `temporal_amount` attributes."
temporal_unit:
type: string
default: ""
description:
"`day`, `week`, `month`, or `year`. If duration is `temporal` then
`temporal_unit` is multiplied by `temporal_amount` to define
the duration that the coupon will be applied to invoices
for."
temporal_amount:
type: integer
default: ""
description:
If duration is `temporal` then `temporal_amount` is an integer
which is multiplied by `temporal_unit` to define the
duration that the coupon will be applied to invoices for.
applies_to_non_plan_charges:
type: boolean
default: "false"
description:
The coupon is valid for one-time, non-plan charges if `true`,
defaults to `false`.
redemption_resource:
type: string
default: account
description:
Whether the discount is for all eligible charges on the account, or
only a specific subscription. Values are `account` or
`subscription`.
max_redemptions_per_account:
type: integer
default: ""
description:
The number of times the coupon can be redeemed on a specific
account. `null` is the default and means unlimited.
coupon_type:
type: string
default: single_code
description:
Whether the coupon is `single_code` or `bulk`. Bulk coupons will
require a `unique_code_template` and will generate unique
codes through the generate endpoint.
unique_code_template:
type: string
default: ""
description:
The template for generating unique codes. See rules below for
creating unique code templates.
plan_codes:
type: array
default: ""
description: Array of `plan_codes` the coupon applies to, if
`applies_to_all_plans` is false.
items:
type: string
item_codes:
type: array
default: ""
description: Array of `item_codes` the coupone applies to, if
`applies_to_all_items` is false.
items:
type: string
free_trial_amount:
type: integer
default: ""
description:
Only relevant when the coupon type is `free_trial`. The
free_trial_amount is used together with free_trial_unit to
define the length of a free trial coupon. For example, a 2
week free trial would be defined as free_trial_amount = 2
and free_trial_unit = Week.
free_trial_unit:
type: string
default: ""
description:
Only relevant when the coupon type is `free_trial`. Allowed values
are `day` or `week` or `month`. free_trial_unit is used
together with free_trial_unit to define the length of a free
trial coupon. For example, a 2 week free trial would be
defined as free_trial_amount = 2 and free_trial_unit = Week.
responses:
"201":
description: ""
content:
application/xml:
example: >-
specialSpecial $2 off couponredeemabledollars2002019-12-31T00:00:00Zfalse200truefalse2018-03-19T16:57:47Z2018-03-19T16:57:47Ztemporalday28falseaccount1single_code2438657833562341574terracottaterrazzomarble
x-codeSamples:
- lang: xml
source: |-
specialSpecial $2 off coupondollars2002019-12-31temporalday282001truesubscription_specialSpecial 10% offpercent102019-12-31200falsegoldplatinumsubscriptionsubscription_specialSpecial 10% offpercent102019-12-31200falseterracottaterrazzomarblesubscription
- lang: PHP
source: >-
coupon_code = 'gorby1';
$coupon->redeem_by_date = '2016-07-04';
$coupon->duration = 'single_use';
$coupon->redemption_resource = 'subscription';
$coupon->max_redemptions_per_account = 1;
$coupon->applies_to_non_plan_charges = true;
// $2 off...
$coupon->name = 'Special $2 off coupon';
$coupon->discount_type = 'dollars';
$coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount
// ...or 10% off.
$coupon->name = 'Special 10% off';
$coupon->discount_type = 'percent';
$coupon->discount_percent = 10;
// Limit to gold and platinum plans only.
$coupon->applies_to_all_plans = false;
$coupon->plan_codes = array('gold', 'platinum');
// Limit to certain items only.
$coupon->applies_to_all_items = false;
$coupon->item_codes = array('terracotta', 'terrazzo', 'marble');
$coupon->create();
print "Coupon: $coupon\n";
} catch (Recurly_ValidationError $e) {
print "Invalid data: $e\n";
}
- lang: Ruby
source: |-
coupon = Recurly::Coupon.new(
:coupon_code => 'special',
:redeem_by_date => Date.new(2014, 1, 1),
:duration => 'single_use'
)
# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = 2_00
# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10
# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = false
coupon.plan_codes = %w(gold platinum)
# Limit to certain items only.
coupon.applies_to_all_items = false
coupon.item_codes = ['terracotta', 'terrazzo', 'marble']
# Limit redemption to specific subscription on account.
coupon.redemption_resource = 'subscription'
# Limit redemptions per account to a specific number.
coupon.max_redemptions_per_account = 1
# Discount should include one-time charges.
coupon.applies_to_non_plan_charges = true
coupon.save
- lang: Python
source: |-
coupon = Coupon(
coupon_code='special',
redeem_by_date=datetime.date(2014, 1, 1),
duration='single_use'
)
# $2 off...
coupon.name = 'Special $2 off coupon'
coupon.discount_type = 'dollars'
coupon.discount_in_cents = Money(200)
# ...or 10% off.
coupon.name = 'Special 10% off'
coupon.discount_type = 'percent'
coupon.discount_percent = 10
# Limit to gold and platinum plans only.
coupon.applies_to_all_plans = False
coupon.plan_codes = ['gold', 'platinum']
# Limit to certain items only.
coupon.applies_to_all_items = False
coupon.item_codes = ['terracotta', 'terrazzo', 'marble']
# Limit redemption to specific subscription on account.
coupon.redemption_resource = 'subscription'
# Limit redemptions per account to a specific number.
coupon.max_redemptions_per_account = 1
# Discount should include one-time charges.
coupon.applies_to_non_plan_charges = True
coupon.save()
- lang: Dotnet
source: >-
// new Coupon(code, name, discount)
// $2 off...
var coupon = new Coupon("special",
"Special $2 off coupon", new Dictionary() { { "USD", 200 } });
// ... or 10% off...
var coupon = new Coupon("special",
"Special 10% off coupon", 10);
coupon.RedeemByDate = new DateTime(2017, 1, 1);
// Limit to gold and platinum plans only.
coupon.AppliesToAllPlans = false;
coupon.Plans.Add("gold");
coupon.Plans.Add("silver");
//Limit to certain items only.
coupon.AppliesToAllItems = false;
coupon.Items.Add("terracotta");
coupon.Items.Add("terrazzo");
coupon.Items.Add("marble");
// Other properties
coupon.RedeemByDate = new DateTime(2014, 1, 1);
coupon.RedemptionResource = Coupon.RedemptionResourceType.Subscription;
coupon.Duration = Coupon.CouponDuration.SingleUse;
coupon.MaxRedemptionsPerAccount = 1;
coupon.AppliesToNonPlanCharges = true;
coupon.Create();
"/coupons/{coupon_code}":
get:
summary: Lookup Coupon
description: >+
Returns information about a coupon. If there are multiple coupons with
the same coupon code, the most recently created coupon is returned.
tags:
- coupons
operationId: lookupCoupon
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2151093486799579392specialSpecial 10% offredeemablepercent102017-12-31T00:00:00Ztrue200false2016-07-11T18:50:17Z2016-07-11T18:50:17Zsingle_usefalseaccountsingle_codegoldplatinumsavemoreSave More Annual Saleredeemabledollars2000falsetrue2015-10-05T16:42:50Ztemporalday28falseaccount1bulk'savemore'99999999100savemore28945343Save More Annual Salemaxed_outdollar2000truefalse2015-10-05T16:42:50Ztemporalday28falseaccount1unique_code2015-10-07T18:48:12Z
x-codeSamples:
- lang: PHP
source: |-
Use the coupon_code of the main coupon campaign, also known as
the prefix, to expire all not yet redeemed unique codes in the campaign.
Use the unique code's coupon_code in order to expire just the specific
unique code.
\ "
tags:
- coupons
operationId: expireCoupon
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
delete();
print "Coupon: $coupon";
} catch (Recurly_NotFoundError $e) {
print "Coupon not found: $e";
}
- lang: Ruby
source: |-
coupon = Recurly::Coupon.find('special')
coupon.destroy
- lang: Python
source: |-
coupon = Coupon.get('special')
coupon.delete()
- lang: Dotnet
source: |-
var coupon = Coupons.Get("special");
coupon.Deactivate();
put:
summary: Edit Coupon
description: >-
Edit a redeemable coupon to extend redemption rules. Only redeemable
coupons can be edited and only the below params are editable.
##### Editing Bulk Coupons and Unique Codes
You can edit a bulk coupon to change the rules of the campaign, but you cannot edit a unique code within the campaign.
tags:
- coupons
operationId: editCoupon
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
name:
type: string
default: ""
description: Coupon name.
description:
type: string
default: ""
description: Description of the coupon on the hosted payment pages.
invoice_description:
type: string
default: ""
description: Description of the coupon on the invoice.
redeem_by_date:
type: string
format: date-time
default: ""
description: Last date to redeem the coupon, defaults to no date.
max_redemptions:
type: integer
default: ""
description:
Maximum number of accounts that may use the coupon before it can no
longer be redeemed.
max_redemptions_per_account:
type: integer
default: ""
description:
The number of times the coupon can be redeemed on a specific
account. `null` is the default and means unlimited.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2151093486799579392specialNew Coupon NameredeemableNew coupon description for the hosted pages.percent10New coupon description for the invoice.2019-12-31T00:00:00Ztrue500false2018-07-11T18:50:17Z2018-07-11T18:52:29Zsingle_usefalseaccount1single_codegoldplatinum
"400":
description: Field Not Editable
content:
application/xml:
example: >-
attributes_not_allowedYou are not allowed to edit attributes discount_type.
x-codeSamples:
- lang: xml
source: >-
New Coupon NameNew coupon description for the hosted pages.New coupon description for the invoice.2019-12-315001
- lang: PHP
source: >-
name = 'New Coupon Name';
$coupon->description = 'New coupon description for the hosted pages.';
$coupon->invoice_description = 'New coupon description for the invoice.';
$coupon->redeem_by_date = '2019-12-31';
$coupon->max_redemptions = 500;
$coupon->max_redemptions_per_account = 1;
$coupon->update();
} catch (Recurly_ValidationError $e) {
print "Invalid data: $e";
}
- lang: Python
source: >-
coupon.name = 'New Coupon Name'
coupon.hosted_description = 'New coupon description for the hosted pages.'
coupon.invoice_description = 'New coupon description for the invoice.'
coupon.redeem_by_date = '2019-12-31'
coupon.max_redemptions = 500
coupon.max_redemptions_per_account = 1
coupon.save()
- lang: Dotnet
source: >-
var coupon = Coupons.Get("special");
coupon.Name = "New Coupon Name";
coupon.HostedDescription = "New coupon description for the hosted pages.";
coupon.InvoiceDescription = "New coupon description for the invoice.";
coupon.RedeemByDate = new DateTime(2019, 12, 31);
coupon.MaxRedemptions = 500;
coupon.MaxRedemptionsPerAccount = 1;
coupon.Update();
"/coupons/{coupon_code}/generate":
post:
summary: Generate Unique Codes
description: >-
Create unique codes for a bulk coupon. A bulk coupon can have up to
100,000 unique codes (or your site's configured limit). The endpoint can be called multiple times to
create the number of unique codes you need.
##### View Unique Codes
The response will include the location of the unique codes as link in the header:
```
https://your-subdomain.recurly.com/v2/coupons/savemore/unique_coupon_codes?cursor=1792526747654056328&per_page=200
```
tags:
- coupons
operationId: generateUniqueCodes
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
number_of_unique_codes:
type: integer
default: ""
description:
Number of unique codes you want to generate for the bulk coupon.
Must be between 1 and 100,000 (or your site's configured limit).
responses:
"201":
description: ""
content:
application/text:
example: >-
HTTP/1.1 201 Created
Content-Type: application/xml; charset=utf-8
Location: https://your-subdomain.recurly.com/v2/coupons/thankyou/unique_coupon_codes?cursor=1998184141762793924%3A1468970111&per_page=200
"400":
description: ""
content:
application/xml:
example: >-
number_of_unique_codesYou are limited to generating 200 at a timenumber_of_unique_codesNumber of unique codes cannot be generated; unique code creation is in progress, please wait for it to finish and try againnumber_of_unique_codesNumber of unique codes can only generate a total of 100000 codesnumber_of_unique_codesCoupon must be of type bulk to generate unique codes
x-codeSamples:
- lang: xml
source: |-
200
- lang: PHP
source: |-
generate(10);
- lang: Ruby
source: |-
unique_codes = coupon.generate(10)
unique_codes.each do |c|
puts c.coupon_code
end
- lang: Python
source: coupons = coupon.generate(10)
- lang: Dotnet
source: var coupons = coupon.Generate(10);
"/coupons/{coupon_code}/restore":
put:
summary: Restore Coupon
description: >-
Make an expired coupon redeemable again. You can change editable fields
in this call.
If you aren't going to change anything in the restore action, include the coupon parameter:
##### Restore Coupon That Reached Redeem By Date
If your coupon has a redeem by date in the past, you must remove the date or change it to a future date, otherwise you will get this error:
```
must be in the future
```
##### Restore Coupon That Reached Max Redemptions
If your coupon has reached it's max redemptions, you must remove the max redemptions or change it to a greater number. You cannot set max redemptions to anything less than the number of redemptions you have. If you do not update max redemptions in this case, you will get this error.
```
must be greater than 100
```
##### Restoring Bulk Coupons or Unique Codes
Restoring a bulk coupon will restore the coupon campaign and all unique codes that have not been redeemed or individually expired.
You can restore an individual unique code if the bulk coupon is active by using the unique code's coupon code in the call.
tags:
- coupons
operationId: restoreCoupon
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
name:
type: string
default: ""
description: Coupon name.
description:
type: string
default: ""
description: Description of the coupon on the hosted payment pages.
invoice_description:
type: string
default: ""
description: Description of the coupon on the invoice.
redeem_by_date:
type: string
format: date-time
default: ""
description: Last date to redeem the coupon, defaults to no date.
max_redemptions:
type: integer
default: ""
description:
Maximum number of accounts that may use the coupon before it can no
longer be redeemed.
max_redemptions_per_account:
type: integer
default: ""
description:
The number of times the coupon can be redeemed on a specific
account. `null` is the default and means unlimited.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2151093486799579392savemoreNew Coupon NameredeemableNew coupon description for the hosted pages.percent10New coupon description for the invoice.2017-12-31T00:00:00Zfalse500true2016-06-05T16:42:32Zforeverfalseaccount1single_code
"400":
description: ""
content:
application/xml:
example: >-
attributes_not_allowedYou are not allowed to edit attributes discount_type.active_couponRestoring an active coupon is not allowed
x-codeSamples:
- lang: xml
source: >-
New Coupon NameNew coupon description for the hosted pages.New coupon description for the invoice.2017-12-315001
- lang: PHP
source: >-
name = 'New Coupon Name';
$coupon->description = 'New coupon description for the hosted pages.';
$coupon->invoice_description = 'New coupon description for the invoice.';
$coupon->redeem_by_date = '2019-12-31';
$coupon->max_redemptions = 500;
$coupon->max_redemptions_per_account = 1;
$coupon->restore();
- lang: Ruby
source: >-
coupon = Recurly::Coupon.find('gorby1')
coupon.name = 'New Coupon Name'
coupon.description = 'New coupon description for the hosted pages.'
coupon.invoice_description = 'New coupon description for the invoice.'
coupon.redeem_by_date = '2019-12-31'
coupon.max_redemptions = 500
coupon.max_redemptions_per_account = 1
coupon.restore!
- lang: Python
source: >-
coupon.name = 'New Coupon Name'
coupon.hosted_description = 'New coupon description for the hosted pages.'
coupon.invoice_description = 'New coupon description for the invoice.'
coupon.redeem_by_date = '2019-12-31'
coupon.max_redemptions = 500
coupon.max_redemptions_per_account = 1
coupon.restore()
- lang: Dotnet
source: >-
var coupon = Coupons.Get("special");
coupon.Name = "New Coupon Name";
coupon.HostedDescription = "New coupon description for the hosted pages.";
coupon.InvoiceDescription = "New coupon description for the invoice.";
coupon.RedeemByDate = new DateTime(2019, 12, 31);
coupon.MaxRedemptions = 500;
coupon.MaxRedemptionsPerAccount = 1;
coupon.Restore();
"/coupons/{coupon_code}/unique_coupon_codes":
get:
summary: List Unique Coupon Codes
description: "\n\n"
tags:
- coupons
operationId: listUniqueCouponCodes
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: redeemed
schema:
type: string
default: ""
description:
Filter unique coupon codes by redemption status. `true` for redeemed,
`false` for not redeemed.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2151093486799579392thankyou26871961Special 10% offredeemablepercent10falsetrue2016-07-19T23:15:12Z2016-07-19T23:15:12Zforeverfalseaccountunique_code
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Coupon with coupon_code = specials
x-codeSamples:
- lang: PHP
source: |-
-
# Code type must be 'Bulk unique codes', e.g. coupon.coupon_type ==
'bulk'
coupon = Recurly::Coupon.find 'bulk-coupon'
coupon.unique_coupon_codes.find_each {|c| puts c.coupon_code}
"/accounts/{account_code}/redemptions/{redemption_uuid}":
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: path
name: redemption_uuid
schema:
type: string
required: true
description: Coupon Redemption's unique uuid.
get:
summary: Lookup Coupon Redemption
description: "\n\n"
tags:
- coupon-redemptions
operationId: lookupCouponRedemption
responses:
"200":
description: ""
content:
application/xml:
example: >-
374a1c75374bd81493a3f7425db0a2b8true0USDactivespecial2016-07-11T18:56:20Z2016-07-11T18:56:20Z
schema:
$ref: "#/components/schemas/Redemption"
x-codeSamples: []
delete:
summary: Remove Coupon Redemption from Account
description:
"Manually expire a coupon redemption on an account. Please note:
the coupon redemption will still count towards the \"maximum redemption
total\" of the coupon.
Specify the specific redemption uuid if you are allowing
multiple active coupon redemptions on an account at a time. Otherwise,
you can do a simple /redemption and automatically remove the most recent
redemption on the account.
\ "
tags:
- coupon-redemptions
operationId: removeCouponRedemptionFromAccount
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
delete();
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
redemption = account.redemption
redemption.destroy
- lang: Python
source: |-
account = Account.get('1')
redemption = account.redemption()
redemption.delete()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var redemption = account.GetActiveRedemption();
redemption.Delete();
"/accounts/{account_code}/redemptions":
get:
summary: List Account's Coupon Redemptions
description:
"Lookup information about the coupon redemptions on an account.
Active and naturally expired limited duration redemptions will be
returned. Redemptions removed from the account or expired single use
coupons will not be returned.
If you use the singular, \"redemption\", in the endpoint, you
will only see the most recently redeemed redemption.
\ "
tags:
- coupon-redemptions
operationId: listAccountsCouponRedemptions
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
example: >-
316a4213e8fa9e97390aff4995bda9e6false0USDactivespecial2016-06-15T17:13:30Z2016-06-15T17:13:30Z3169fd6127ff82ccbfa08a442188d575false1500USDactivespecial2016-05-27T12:34:56Z2016-06-15T17:13:30Z
x-codeSamples:
- lang: PHP
source: |-
redemptions) {
$redemptions = $account->redemptions->get();
print "Redemptions: $redemptions";
}
} catch (Recurly_NotFoundError $e) {
print "Account not found: $e";
}
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
redemptions = account.redemptions
- lang: Python
source: |-
account = Account.get('1')
redemptions = account.redemptions()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var redemptions = account.GetActiveRedemptions();
"/invoices/{invoice_number}/redemptions":
get:
summary: List Invoice's Coupon Redemptions
description: "Returns all coupon redemptions that discounted the invoice.
If you use the singular, \"redemption\", in the endpoint, you
will only see the first redemption applied to the invoice.
\ "
tags:
- coupon-redemptions
operationId: listInvoicesCouponRedemptions
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
example: >-
316a4213e8fa9e97390aff4995bda9e6false100USDactivespecial2016-06-15T17:13:30Z2016-06-15T17:13:30Z3169fd6127ff82ccbfa08a442188d575false1500USDactivespecial2016-05-27T12:34:56Z2016-06-15T17:13:30Z
x-codeSamples:
- lang: PHP
source: |-
redemptions) {
$redemptions = $invoice->redemptions->get();
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1')
redemptions = invoice.redemptions
- lang: Python
source: |-
invoice = Invoice.get('1')
redemptions = invoice.redemptions()
- lang: Dotnet
source: |-
var invoice = Invoices.Get(1);
var redemptions = invoice.GetRedemptions();
"/subscriptions/{uuid}/redemptions":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
get:
summary: List Subscription's Coupon Redemption
description: >+
Returns an array of active coupon redemptions associated with the
specific subscription. Coupon redemptions are only associated with a
subscription if the coupon has a discount level of "subscription".
Inactive coupon redemptions will not be returned.
tags:
- coupon-redemptions
operationId: listSubscriptionsCouponRedemption
parameters:
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: path
name: uuid
schema:
type: string
required: true
description: Uuid.
responses:
"200":
description: ""
content:
application/xml:
example: >-
376e95a50fd77b5da9a727411bab7c54false450EURactivesubscription_special2016-07-18T20:55:02Z2016-07-18T20:55:02Z
x-codeSamples:
- lang: PHP
source: >
redemptions->get();
- lang: Ruby
source: >-
subscription = Recurly::Subscription.find
'376e95a4e15229034db706494a8cf445'
redemptions = subscription.redemptions
- lang: Python
source: |-
sub = recurly.Subscription.get('376e95a4e15229034db706494a8cf445')
redemptions = sub.redemptions()
- lang: Dotnet
source: |-
var sub = Subscriptions.Get("376e95a4e15229034db706494a8cf445");
var redemptions = sub.GetRedemptions();
"/coupons/{coupon_code}/redeem":
post:
summary: Redeem Coupon on Account
description: >-
Redeem a coupon on an existing customer's account to apply to their next
invoice.
If you want the coupon redemption to be rejected if a subscription signup fails, you must redeem the coupon within the Create Subscription call, not in the Redeem on Account call.
##### Redeeming Multiple Coupons
If you have Multiple Coupons Per Account enabled in Coupon Settings, you can have multiple active redemptions on an account. Call this redeem endpoint multiple times to redeem more than one coupon.
##### Maxed Out Error
If a coupon can only be redeemed on an account a specific number of times and you have already redeemed the coupon that number of times on the account, you will see a maxed out error letting you know the coupon can no longer be redeemed on the account.
```
Coupon has reached max redemptions for this account
```
The only way you would be able to redeem this coupon again on the account would be to update the main coupon campaign to allow more redemptions per account.
##### Subscription-Level Redemption
If the coupon is subscription-level, meaning it has a redemption_resource of "subscription", you must specify the subscription_uuid of an existing subscription on the account that you want to tie the redemption to. Otherwise you will get this error:
```
must be redeemed on a subscription
```
If the subscription_uuid you provide is for a subscription with a plan not eligible for the coupon, you will see this error:
```
not valid for this coupon
```
tags:
- coupon-redemptions
operationId: redeemCouponOnAccount
parameters:
- in: path
name: coupon_code
schema:
type: string
default: ""
required: true
description: Unique code to identify and redeem the coupon.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- account_code
- currency
properties:
account_code:
type: integer
default: ""
description: Account code to apply redemption
currency:
type: string
default: ""
description: Currency for the redemption.
subscription_uuid:
type: string
default: ""
description:
If the coupon has a `redemption_resource` of `subscription`, you
will need to specify the uuid of an existing subscription on
the account, which you want to tie the redemption to.
responses:
"201":
description: ""
content:
application/xml:
example: >-
374a1c75374bd81493a3f7425db0a2b8true0USDactivespecial2016-07-11T18:56:20Z2016-07-11T18:56:20Z
schema:
$ref: "#/components/schemas/Redemption"
"400":
description: Expired/Invalid
content:
application/xml:
example: >-
not_foundCouldn't find Coupon with coupon_code = savemore
x-codeSamples:
- lang: xml
source: |-
1USD
- lang: PHP
source: |-
redeemCoupon('1', 'USD');
- lang: Ruby
source: |-
account = Recurly::Account.find('1')
coupon = Recurly::Coupon.find('special')
redemption = coupon.redeem(account)
- lang: Python
source: >-
coupon = Coupon.get('special')
redemption = Redemption(account_code='1', currency='USD')
# new redemption object returned from this method will contain the updates
# so we overwrite the redemption variable
redemption = coupon.redeem(redemption)
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var redemption = account.RedeemCoupon("special", "USD");
"/dunning_campaigns":
get:
summary: List Dunning Campaigns
description: >+
Returns a list of active dunning campaigns on your site.
tags:
- dunning-campaigns
operationId: listDunningCampaigns
responses:
"200":
description: ""
content:
application/xml:
example: >-
p7gnbhfxbe8orest testrestfalse2021-07-14T17:28:53Z2021-07-14T17:28:53Zautomaticfalse0false0payment_declinedtruetrue101012021-07-14T17:28:53Z2021-07-14T17:28:53Z
x-codeSamples:
- lang: PHP
source: |-
+
Returns a specific campaign's details.
tags:
- dunning-campaigns
operationId: getDunningCampaign
parameters:
- in: path
name: id
schema:
type: string
required: true
description: The id of the dunning campaign you want to look up.
responses:
"200":
description: ""
content:
application/xml:
example: >-
p7gnbhfxbe8orest testrestfalse2021-07-14T17:28:53Z2021-07-14T17:28:53Zautomaticfalse0false0payment_declinedtruetrue101012021-07-14T17:28:53Z2021-07-14T17:28:53Z
schema:
$ref: "#/components/schemas/DunningCampaign"
x-codeSamples:
- lang: PHP
source: |-
+
Assign a dunning campaign to multiple plans.
tags:
- dunning-campaigns
operationId: putDunningCampaignBulkUpdate
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- plan_codes
properties:
plan_codes:
type: array
description:
List of `plan_codes` associated with the Plans for which the
dunning campaign should be updated.
items:
type: string
responses:
"204":
description: ""
content:
application/xml:
example: >-
x-codeSamples:
- lang: PHP
source: |-
bulkUpdate($plan_codes);
- lang: Ruby
source: |-
campaign = Recurly::DunningCampaign.find('pbux7jvmauhe')
plan_codes = ['platinum', 'gold']
campaign.bulk_update(plan_codes)
- lang: Python
source: |-
campaign = recurly.DunningCampaign.get("pbux7jvmauhe")
plan_codes = ["platinum", "gold"]
campaign.bulk_update("pbux7jvmauhe", plan_codes)
- lang: Dotnet
source: |-
var campaign = DunningCampaign.Get("pbux7jvmauhe");
var plan_codes = new string[]{ "platinum", "gold" };
campaign.BulkUpdate(plan_codes);
"/accounts/{account_code}/entitlements":
get:
summary: List Account's Entitlements
description: |+
List entitlements granted to an account.
tags:
- accounts
operationId: listEntitlements
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: The account code of the account you want to look up.
- in: query
name: state
schema:
type: string
default: all
description: |+
Filter the entitlements based on the state of the applicable subscription."
When `state=active`, `state=canceled`, `state=expired`, or `state=future`,
subscriptions with states that match the query and only those subscriptions will be returned.
When no state is provided, subscriptions with active or canceled states will be returned."
responses:
"200":
description: ""
content:
application/xml:
example: >-
rpnpgqjh7wp6premium_showsPremium Showspremium content2022-10-12T17:25:28Z2022-10-12T17:25:28Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: PHP
source: |-
+
Returns a list of all invoice templates on your site.
tags:
- invoice-templates
operationId: listInvoiceTemplates
responses:
"200":
description: ""
content:
application/xml:
example: >-
p7gnbhfxbe8oDefault Templatedefault2021-07-14T17:28:53Z2021-07-14T17:28:53Zei7nj4ddt65wNew Header Image Templatenew_headerTemplate to use new header image2022-02-03T10:12:51Z2022-02-03T10:12:51Z
x-codeSamples:
- lang: PHP
source: |-
+
Returns a specific invoice templates's details.
tags:
- invoice-templates
operationId: getInvoiceTemplate
parameters:
- in: path
name: uuid
schema:
type: string
default: ""
required: true
description: The uuid of the invoice template you want to look up.
responses:
"200":
description: ""
content:
application/xml:
example: >-
ei7nj4ddt65wNew Header Image Templatenew_headerTemplate to use new header image2022-02-03T10:12:51Z2022-02-03T10:12:51Z
schema:
$ref: "#/components/schemas/InvoiceTemplate"
x-codeSamples:
- lang: PHP
source: |-
+
Returns a list of the accounts that use the specified template to generate invoices.
tags:
- accounts
operationId: getInvoiceTemplateAccounts
parameters:
- in: path
name: uuid
schema:
type: string
default: ""
required: true
description: The uuid of the invoice template for which you want a list of accounts.
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of accounts to return: `active`, `closed`, `subscriber`,
`non_subscriber`, `past_due`."
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: integer
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Account"
example: >-
1activeverena1234verena@example.combob@example.com,susan@example.comVerenaExampleNew Company Namefalse123 Main St.San FranciscoCA94105USsizelarge71c122cb16fc90252ff845eacf5d78142016-08-03T15:44:05Z2017-03-15T21:22:18Zfalsefalsefalsefalsefalse
"/general_ledger_accounts":
get:
tags:
- general_ledger_accounts
operationId: list_general_ledger_accounts
summary: List general ledger accounts
parameters:
- in: query
name: account_type
schema:
type: string
description:
"The account type of general ledger accounts to return: `liability`,
`revenue`."
responses:
"200":
description: Returns a list of general ledger accounts on your site.
content:
application/xml:
schema:
"$ref": "#/components/schemas/GeneralLedgerAccountsList"
examples:
getAllGla:
"$ref": "#/components/examples/GeneralLedgerAccountsListResponse"
x-codeSamples:
- lang: PHP
source: |-
code\n";
}
} catch(Recurly_Error $e) {
print("Caught an error:\n");
print($e);
}
- lang: Python
source: |-
# account_type is an optional filter and can take either 'liability' or 'revenue'
glas = GeneralLedgerAccount.all(account_type='revenue')
for general_ledger_account in glas:
print(f'General Ledger Account: {general_ledger_account}')
- lang: Ruby
source: |-
# optional filter (revenue, liability)
options = { account_type: 'revenue' }
Recurly::GeneralLedgerAccount.find_each(options) do |gla|
puts "General Ledger Account: #{gla.inspect}"
end
- lang: Dotnet
source: |-
var glas = GeneralLedgerAccounts.List();
// in addition to FilterCriteria, can also filter by account type:
// var glas = GeneralLedgerAccounts.List(GeneralLedgerAccountType.Liability);
do
{
foreach (var gla in glas)
{
Console.WriteLine("GLA ({0}): {1}", gla.AccountType, gla.Code);
}
glas = glas.Next;
} while (glas.HasNextPage());
- lang: Java
source: |-
final GeneralLedgerAccounts generalLedgerAccounts = client.getGeneralLedgerAccounts();
// Can filter by account type.
// final GeneralLedgerAccount glas = client.getGeneralLedgerAccounts("revenue");
for (GeneralLedgerAccount generalLedgerAccount : generalLedgerAccounts) {
System.out.println("GeneralLedgerAccount: " + generalLedgerAccount);
}
post:
tags:
- general_ledger_accounts
operationId: create_general_ledger_account
summary: Create a new general ledger account
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/GeneralLedgerAccountCreate"
examples:
glaCreateRequest:
$ref: "#/components/examples/GeneralLedgerAccountCreateRequest"
responses:
"201":
description: A new general ledger account.
content:
application/xml:
schema:
$ref: "#/components/schemas/GeneralLedgerAccount"
examples:
createGla:
"$ref": "#/components/examples/GeneralLedgerAccountResponse"
x-codeSamples:
- lang: PHP
source: |-
code = $code;
// account type can be liability or revenue
$gla->account_type = 'liability';
$gla->description = $description;
$gla->create();
print "General Ledger Account: $gla\n";
} catch (Exception $e) {
print "Error: $e";
}
- lang: Python
source: |-
# account_type can be 'liability' or 'revenue'
gla = GeneralLedgerAccount(
code=gla_code,
account_type='revenue',
description="An optional description"
)
gla.save()
- lang: Ruby
source: |-
begin
gla_description = Faker::Hipster.words(number: 3).join(' ')
gla_code = Faker::Lorem.characters(number: 6)
Recurly::GeneralLedgerAccount.create!(
description: gla_description,
code: gla_code,
account_type: 'revenue'
)
rescue Recurly::Error => e
puts e.inspect
end
- lang: Dotnet
source: |-
// account type can be Liability or Revenue
var gla = new GeneralLedgerAccount(yourAccountingCode, GeneralLedgerAccountType.Liability)
{
Description = "An optional description",
};
gla.Create();
- lang: Java
source: |-
// account type can be liability or revenue
final GeneralLedgerAccount gla = new GeneralLedgerAccount();
gla.setCode("code1");
gla.setAccountType(["revenue"|"liability"]);
gla.setDescription("Look at this fun General Ledger Account description!");
final GeneralLedgerAccount glaResponse = client.createGeneralLedgerAccount(gla);
"/performance_obligations/{performance_obligation_id}":
get:
tags:
- performance_obligations
operationId: get_performance_obligation
summary: Get a single Performance Obligation
parameters:
- "$ref": "#/components/parameters/performance_obligation_id"
responses:
"200":
description: A single Performance Obligation.
content:
application/xml:
schema:
"$ref": "#/components/schemas/PerformanceObligation"
examples:
getOnePob:
"$ref": "#/components/examples/PerformanceObligationsResponse"
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
name\n");
} catch(Recurly_Error $e) {
print("Caught an error:\n");
print($e);
}
- lang: Ruby
source: |-
begin
pob = Recurly::PerformanceObligation.find(id)
puts "Performance Obligation name: #{pob.name}"
rescue Recurly::Error => e
puts e.inspect
end
- lang: Python
source: |-
pob = PerformanceObligation.get(id)
print(f'Performance Obligation: {pob}')
- lang: Dotnet
source: |-
var pob = PerformanceObligations.Get(id);
- lang: Java
source: |-
final PerformanceObligation pob = client.getPerformanceObligation(id);
"/performance_obligations":
get:
tags:
- performance_obligations
operationId: get_performance_obligations
summary: Get a site's Performance Obligations
responses:
"200":
description: A list of Performance Obligations.
content:
application/xml:
schema:
"$ref": "#/components/schemas/PerformanceObligationList"
examples:
getAllPobs:
"$ref": "#/components/examples/PerformanceObligationsListResponse"
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
name\n";
}
} catch(Recurly_Error $e) {
print("Caught an error:\n");
print($e);
}
- lang: Ruby
source: |-
Recurly::PerformanceObligation.find_each do |pob|
puts "Performance Obligation name: #{pob.name}"
end
- lang: Python
source: |-
pobs = PerformanceObligation.all()
for performance_obligation in pobs:
print(f'Performance Obligation: {performance_obligation}')
- lang: Dotnet
source: |-
var pobs = PerformanceObligations.List();
do
{
foreach (var pob in pobs)
{
Console.WriteLine("Performance Obligation: {0}", pob.Name);
}
pobs = pobs.Next;
} while (pobs.HasNextPage());
- lang: Java
source: |-
final PerformanceObligations performanceObligations = client.getPerformanceObligations();
for (PerformanceObligation performanceObligation : performanceObligations) {
System.out.println("PerformanceObligation: " + performanceObligation);
}
"/general_ledger_accounts/{general_ledger_account_id}":
get:
tags:
- general_ledger_accounts
operationId: lookup_general_ledger_account
summary: Lookup general ledger account
parameters:
- "$ref": "#/components/parameters/general_ledger_account_id"
required: true
responses:
"200":
description: The general ledger account.
content:
application/xml:
schema:
"$ref": "#/components/schemas/GeneralLedgerAccount"
examples:
getOneGla:
"$ref": "#/components/examples/GeneralLedgerAccountResponse"
x-codeSamples:
- lang: PHP
source: |-
e
puts e.inspect
end
- lang: Dotnet
source: |-
var gla = GeneralLedgerAccounts.Get(existingGlaId);
- lang: Java
source: |-
final GeneralLedgerAccount generalLedgerAccount = client.getGeneralLedgerAccount(glaId);
put:
tags:
- general_ledger_accounts
operationId: update_general_ledger_account
summary: Update a general ledger account
parameters:
- "$ref": "#/components/parameters/general_ledger_account_id"
requestBody:
content:
application/xml:
schema:
"$ref": "#/components/schemas/GeneralLedgerAccountUpdate"
examples:
glaUpdateRequest:
$ref: "#/components/examples/GeneralLedgerAccountUpdateRequest"
required: true
responses:
"200":
description: The updated general ledger account.
content:
application/xml:
schema:
"$ref": "#/components/schemas/GeneralLedgerAccount"
examples:
updateGla:
"$ref": "#/components/examples/GeneralLedgerAccountResponse"
"404":
description: Incorrect site or general ledger account ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
description = 'A new general_ledger_account description';
$general_ledger_account->update();
print("New gla: $general_ledger_account\n");
}
catch (Recurly_ValidationError $e) {
print($e->getMessage()."\n");
}
- lang: Python
source: |-
gla = GeneralLedgerAccount.get(existing_gla_id)
# can also update the code, but _not_ the account_type
gla.description = "New description"
gla.save()
- lang: Ruby
source: |-
begin
gla = Recurly::GeneralLedgerAccount.find(id)
gla.update_attributes(
description: "New description"
)
gla.save!
rescue Recurly::Error => e
puts e.inspect
end
- lang: Dotnet
source: |-
var gla = GeneralLedgerAccounts.Get(existingGlaId);
// can also update the Code, but _not_ the AccountType
gla.Description = "This is a new description";
gla.Update();
- lang: Java
source: |-
final GeneralLedgerAccount gla = client.getGeneralLedgerAccount(existingGlaId);
gla.setDescription("This is a new description");
final GeneralLedgerAccount updatedGla = client.updateGeneralLedgerAccount(existingGlaId, gla);
"/gift_cards":
get:
summary: List Gift Cards
description: >+
Returns a list of all purchased gift cards on your site, across all
accounts.
Note: To use the gift cards API endpoints, some configuration is required. Please see [our docs](https://docs.recurly.com/docs/gift-cards) for further instructions.
tags:
- gift-cards
operationId: listGiftCards
parameters:
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: gifter_account_code
schema:
type: string
default: ""
description:
Filters the gift cards list to only those purchased by this account
code.
- in: query
name: recipient_account_code
schema:
type: string
default: ""
description:
Filters the gift cards list to only those redeemed by this account
code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2003020297591186183518822D87268C142500gift_card1000USDpostjohn@example.comJohnSmith123 B St.San FranciscoCA94110USASally
Hi John, Happy Birthday! I hope you have a great day! Love, Sally2016-07-26T15:23:46Z2016-07-29T04:25:39Z2016-07-29T04:25:38Zt5ejtgf1vxt5ejtgf2rft5ejtge1xw19885961868277278383E687AE878D37EBDgift_card1000USDemailjill@example.comJillWilson
Happy Holidays!2016-12-14T15:23:46Z2016-12-14T15:23:46Z2016-12-14T15:23:46Zt5ejtgf1vxt5ejtgf2rft5ejtge1xw
x-codeSamples:
- lang: PHP
source: >-
product_code - $card->redemption_code";
if ($card->redeemed_at) print " - {$card->redeemed_at->format('c')}";
print "\n";
}
- lang: Ruby
source: |-
Recurly::GiftCard.find_each do |gift_card|
puts "Susbcription: #{gift_card}"
end
- lang: Python
source: |-
for gift_card in recurly.GiftCard.all():
print 'Gift Card: %s' % gift_card
- lang: Dotnet
source: >
string gifterAccountCode = "benjamin-du-monde";
string recipientAccountCode = "sally-du-monde";
var filter = FilterCriteria.Instance
.WithOrder(FilterCriteria.Order.Desc)
.WithSort(FilterCriteria.Sort.CreatedAt)
.WithBeginTime(new DateTime(2015, 1, 1))
.WithEndTime(DateTime.UtcNow);
// all of these parameters are nullable or can be omitted entirely. examples:
// var gcList = GiftCards.List();
// var gcList = GiftCards.List(null, null, filter);
var gcList = GiftCards.List(gifterAccountCode, recipientAccountCode, filter);
while (gcList.HasAny())
{
foreach (var gc in gcList)
{
Console.WriteLine(gc);
}
gcList = gcList.Next;
}
post:
summary: Create Gift Card
description: >+
Purchase a gift card on the gifter's account.
Note: To use the gift cards API endpoints, some configuration is required. Please see [our docs](https://docs.recurly.com/docs/gift-cards) for further instructions.
tags:
- gift-cards
operationId: createGiftCard
parameters: []
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- product_code
- unit_amount_in_cents
- currency
- delivery
- method
- gifter_account
- account_code
properties:
product_code:
type: string
default: ""
description: The product code of the gift card product.
unit_amount_in_cents:
type: integer
default: ""
description:
The amount of the gift card. Must match an amount on the gift card
product.
currency:
type: string
default: ""
description: The currency of the `unit_amount_in_cents`.
tax_service_opt_out:
type: boolean
default: false
description: Set to `true` to bypass sending the purchase to your configured tax service. Defaults to `false`.
delivery:
type: object
default: ""
description:
Block of delivery information. Includes the params `method` through
`personal_message` below.
method:
type: string
default: ""
description: Whether the delivery method is `email` or `post`.
deliver_at:
type: string
format: date-time
default: ""
description:
When the gift card should be delivered to the recipient. If null,
the gift card will be delivered immediately. If a datetime
is provided, the delivery will be in an hourly window,
rounding down. For example, 6:23 pm will be in the 6:00 pm
hourly batch. Must be at least an hour in the future and
less than a year in the future
email_address:
type: string
default: ""
description: The email address of the recipient. Required if `method` = `email`.
first_name:
type: string
default: ""
description: The first name of the recipient.
last_name:
type: string
default: ""
description: The last name of the recipient.
address:
type: object
default: ""
description:
Block of address information for the recipient. Includes the params
`address1` through `phone` below. Required if `method` =
`post`.
address1:
type: string
default: ""
description:
The first street address line of the recipient. Required if
`method` = `post`.
address2:
type: string
default: ""
description: The second street address line of the recipient.
city:
type: string
default: ""
description: The city of the recipient. Required if `method` = `post`.
state:
type: string
default: ""
description:
The state/province of the recipient. Required if `method` = `post`
and `country` = US, CA, IT or NL.
zip:
type: string
default: ""
description:
The zip/postal code of the recipient. Required if `method` =
`post`.
country:
type: string
default: ""
description: The country of the recipient. Required if `method` = `post`.
phone:
type: string
default: ""
description: The phone number of the recipient.
gifter_name:
type: string
default: ""
description:
The name of the gifter for the purpose of message displays to the
recipient.
personal_message:
type: string
default: ""
description:
The personal message from the gifter to the recipient. 255
characters.
gifter_account:
type: object
default: ""
description:
Block of account details for the gifter. This can reference an
existing `account_code` or create a new account using the
Account objects params. An `account_code` is required.
account_code:
type: string
default: ""
description: The account code of the gifter's account.
billing_info:
type: object
default: ""
description: Accepts nested three_d_secure_action_result_token_id (string)
responses:
"201":
description: ""
content:
application/xml:
examples:
gcResponse:
$ref: "#/components/examples/GiftCardResponse"
schema:
$ref: "#/components/schemas/GiftCard"
"404":
description: ""
content:
application/xml:
example: >-
not_foundGift card product with unit amount in cents of '2000' and 'USD' currency not foundnot_foundGift card product with product code 'gift_cards123' not found
x-codeSamples:
- lang: xml
source: >-
gift_card2000USDtrueemailjohn@example.comJohnSmithSally
Hi John, Happy Birthday! I hope you have a great day! Love, Sally1sally@example.comSallyWilson4111-1111-1111-111112017
- lang: Ruby
source: >-
Recurly::GiftCard.create(
product_code: 'gift_card',
unit_amount_in_cents: 2000,
currency: 'USD',
delivery: {
method: 'email',
email_address: 'john@example.com',
first_name: 'John',
last_name: 'Smith',
address: {
address1: '',
address2: '',
city: '',
state: '',
zip: '',
country: '',
phone: '',
},
gifter_name: 'Sally',
personal_message: 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally',
},
gifter_account: {
account_code: '1',
email: 'sally@example.com',
first_name: 'Sally',
last_name: 'Wilson',
billing_info: {
number: '4111-1111-1111-1111',
month: '1',
year: '2017'
}
}
)
- lang: PHP
source: >-
product_code = 'gift_card';
$giftCard->currency = 'USD';
$giftCard->unit_amount_in_cents = 1000;
$giftCard->gifter_account = new Recurly_Account('3345634');
$giftCard->delivery = new Recurly_Delivery();
$giftCard->delivery->email_address = 'john@example.com';
$giftCard->delivery->first_name = 'John';
$giftCard->delivery->last_name = 'Smith';
$giftCard->delivery->personal_message= 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally';
$giftCard->delivery->gifter_name = 'Sally';
$giftCard->delivery->method = 'email'; //email or post
$giftCard->delivery->deliver_at = new DateTime("2017-01-01 00:00:00", new DateTimeZone("UTC"));
$giftCard->create();
- lang: Python
source: >-
gift_card = recurly.GiftCard()
gift_card.product_code = 'gift_card'
gift_card.currency = 'USD'
gift_card.unit_amount_in_cents = 1000
gift_card.gifter_account = recurly.Account(account_code='3345634')
delivery = recurly.Delivery()
delivery.method = 'email'
delivery.email_address = 'john@example.com'
delivery.first_name = 'John'
delivery.last_name = 'Smith'
delivery.personal_message = 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally'
delivery.gifter_name = 'Sally'
gift_card.delivery = delivery
gift_card.save()
- lang: Dotnet
source: >-
var delivery = new Delivery(Delivery.DeliveryMethod.Email);
delivery.GifterName = "Benjamin";
delivery.FirstName = "Sally";
delivery.LastName = "DuMonde";
delivery.PersonalMessage = "Happy birthday!";
delivery.EmailAddress = "sally@example.com";
// the first param can be an account code for the gifter (if it exists) or an Account object for a new account
var giftCard = new GiftCard("benjamin-du-monde", delivery, "test_gift_card", 1000, "USD");
giftCard.Create();
"/gift_cards/preview":
post:
summary: Preview Gift Card
description: >-
Preview a gift card purchase. Allows the gifter to confirm that the
delivery details provided are correct.
Note: To use the gift cards API endpoints, some configuration is required. Please see [our docs](https://docs.recurly.com/docs/gift-cards) for further instructions.
##### Preview Response
The preview response will be slightly different than the purchase response:
* The gift card object will not have a reference link.
* The `id` will be `nil`.
* The redemption code will be `nil`.
* A new attribute called `checkout_cost` will be included. This will always match the `unit_amount_in_cents` for now. In the future, when we support coupon discounts on gift card purchases, `checkout_cost` will be the after discount cost to the gifter.
tags:
- gift-cards
operationId: previewGiftCard
parameters: []
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- product_code
- unit_amount_in_cents
- currency
- delivery
- method
- gifter_account
- account_code
properties:
product_code:
type: string
default: ""
description: The product code of the gift card product.
unit_amount_in_cents:
type: integer
default: ""
description:
The amount of the gift card. Must match an amount on the gift card
product.
currency:
type: string
default: ""
description: The currency of the `unit_amount_in_cents`.
tax_service_opt_out:
type: boolean
default: false
description: Set to `true` to bypass sending the purchase to your configured tax service. Defaults to `false`.
delivery:
type: object
default: ""
description:
Block of delivery information. Includes the params `method` through
`personal_message` below.
method:
type: string
default: ""
description: Whether the delivery method is `email` or `post`.
email_address:
type: string
default: ""
description: The email address of the recipient. Required if `method` = `email`.
first_name:
type: string
default: ""
description: The first name of the recipient.
last_name:
type: string
default: ""
description: The last name of the recipient.
address:
type: object
default: ""
description:
Block of address information for the recipient. Includes the params
`address1` through `phone` below. Required if `method` =
`post`.
address1:
type: string
default: ""
description:
The first street address line of the recipient. Required if
`method` = `post`.
address2:
type: string
default: ""
description: The second street address line of the recipient.
city:
type: string
default: ""
description: The city of the recipient. Required if `method` = `post`.
state:
type: string
default: ""
description:
The state/province of the recipient. Required if `method` = `post`
and `country` = US, CA, IT or NL.
zip:
type: string
default: ""
description:
The zip/postal code of the recipient. Required if `method` =
`post`.
country:
type: string
default: ""
description: The country of the recipient. Required if `method` = `post`.
phone:
type: string
default: ""
description: The phone number of the recipient.
gifter_name:
type: string
default: ""
description:
The name of the gifter for the purpose of message displays to the
recipient.
personal_message:
type: string
default: ""
description:
The personal message from the gifter to the recipient. 255
characters.
gifter_account:
type: object
default: ""
description:
Block of account details for the gifter. This can reference an
existing `account_code` or create a new account using the
Account objects params. An `account_code` is required.
account_code:
type: string
default: ""
description: The account code of the gifter's account.
responses:
"200":
description: ""
content:
application/xml:
examples:
gcResponse:
$ref: "#/components/examples/GiftCardResponse"
schema:
$ref: "#/components/schemas/GiftCard"
"404":
description: Wrong Amount
content:
application/xml:
example: >-
not_foundGift card product with unit amount in cents of '2000' and 'USD' currency not found
x-codeSamples:
- lang: xml
source: >-
gift_card2000USDtrueemailjohn@example.comJohnSmithSallyHi John, Happy Birthday! I hope you have a great day! Love, Sally1sally@example.comSallyWilson4111-1111-1111-111112017
- lang: Ruby
source: >
Recurly::GiftCard.preview(
product_code: 'gift_card',
unit_amount_in_cents: 2000,
currency: 'USD',
delivery: {
method: 'email',
email_address: 'john@example.com',
first_name : 'John',
last_name: 'Smith',
address: {
address1: '',
address2: '',
city: '',
state: '',
zip: '',
country: '',
phone: '',
},
gifter_name: 'Sally',
personal_message: 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally',
},
gifter_account: {
account_code: '1',
email: 'sally@example.com',
first_name: 'Sally',
last_name: 'Wilson',
billing_info: {
number: '4111-1111-1111-1111',
month: '1',
year: '2017'
}
}
)
- lang: PHP
source: >-
product_code = 'gift_card';
$giftCard->currency = 'USD';
$giftCard->unit_amount_in_cents = 1000;
$giftCard->gifter_account = new Recurly_Account('3345634');
$giftCard->delivery = new Recurly_Delivery();
$giftCard->delivery->email_address = 'john@example.com';
$giftCard->delivery->first_name = 'John';
$giftCard->delivery->last_name = 'Smith';
$giftCard->delivery->personal_message= 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally';
$giftCard->delivery->gifter_name = 'Sally';
$giftCard->delivery->method = 'email'; //email or post
$giftCard->preview();
- lang: Python
source: >-
gift_card = recurly.GiftCard()
gift_card.product_code = 'gift_card'
gift_card.currency = 'USD'
gift_card.unit_amount_in_cents = 1000
gift_card.gifter_account = recurly.Account(account_code='3345634')
delivery = recurly.Delivery()
delivery.method = 'email'
delivery.email_address = 'john@example.com'
delivery.first_name = 'John'
delivery.last_name = 'Smith'
delivery.personal_message = 'Hi John, Happy Birthday! I hope you have a great day! Love, Sally'
delivery.gifter_name = 'Sally'
gift_card.delivery = delivery
gift_card.preview()
- lang: Dotnet
source: >-
var delivery = new Delivery(Delivery.DeliveryMethod.Email);
delivery.GifterName = "Benjamin";
delivery.FirstName = "Sally";
delivery.LastName = "DuMonde";
delivery.PersonalMessage = "Happy birthday!";
delivery.EmailAddress = "sally@example.com";
// the first param can be an account code for the gifter (if it exists) or an Account object for a new account
var giftCard = new GiftCard("benjamin-du-monde", delivery, "test_gift_card", 1000, "USD");
giftCard.Preview();
"/gift_cards/{id}":
get:
summary: Lookup Gift Card
description: >+
Note: To use the gift cards API endpoints, some configuration is
required. Please see [our
docs](https://docs.recurly.com/docs/gift-cards) for further
instructions.
tags:
- gift-cards
operationId: lookupGiftCard
parameters:
- in: path
name: id
schema:
type: string
default: ""
required: true
description: The id of the gift card you want to look up.
responses:
"200":
description: ""
content:
application/xml:
examples:
gcResponse:
$ref: "#/components/examples/GiftCardResponse"
schema:
$ref: "#/components/schemas/GiftCard"
x-codeSamples:
- lang: PHP
source: |-
+
Redeem a gift card on a recipient's account, outside of a subscription
purchase.
Note: To use the gift cards API endpoints, some configuration is required. Please see [our docs](https://docs.recurly.com/docs/gift-cards) for further instructions.
tags:
- gift-cards
operationId: redeemGiftCardOnAccount
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- recipient_account
- account_code
properties:
recipient_account:
type: object
default: ""
description: The account object for the recipient of the gift card.
account_code:
type: string
default: ""
description: The account code of the recipient. Must be an existing account.
responses:
"200":
description: ""
content:
application/xml:
examples:
gcResponse:
$ref: "#/components/examples/GiftCardResponse"
schema:
$ref: "#/components/schemas/GiftCard"
"400":
description: ""
content:
application/xml:
example: >-
bad_requestThis gift card has already been redeemed.bad_requestGift Card with redemption code '5B88C922ABD00559F' not foundbad_requestAccount with account code '059903imfkejfhs' not found
x-codeSamples:
- lang: xml
source: |-
3345700
- lang: PHP
source: |-
redemption_code = $redemptionCode;
$giftCard->redeem($accountCode);
- lang: Ruby
source: |-
account_code = '3345634'
redemption_code = '22FD95994D02B39D'
gift_card = Recurly::GiftCard.new(redemption_code: redemption_code)
gift_card.redeem(account_code)
- lang: Python
source: |-
account_code = '3345634'
redemption_code = '22FD95994D02B39D'
gift_card = recurly.GiftCard(redemption_code=redemption_code)
gift_card.redeem(account_code)
- lang: Dotnet
source: |-
var redemptionCode = "22FD95994D02B39D";
var accountCode = "3345634";
var giftcard = new GiftCard(redemptionCode);
giftcard.Redeem(accountCode);
"/invoices":
get:
summary: List Invoices
description: "Returns a list of all invoices.
**INVOICE STATES**
| State | Description |
| --- | --- |
| `pending` | Outstanding collection, not paid or past due |
| `paid` | Collection completed successfully |
| `failed` | Failed to collect |
| `past_due` | Initial collection failed, still attempting
collection |
| `open` | Outstanding credit balance (credit invoice only) |
| `closed` | No remaining outstanding credit balance (credit
invoice only) |
| `voided` | Credit invoice voided (credit invoice only) |
| `processing` | Transaction initiated but no response yet |
Please note: an invoice will only be in one state.
\ "
tags:
- invoices
operationId: listInvoices
parameters:
- in: query
name: state
schema:
type: string
default: all
description:
"The state of invoices to return: `pending`, `paid`, `failed`,
`past_due`, `open`, `closed`, `voided`, or `processing`"
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US3c42a34e49efd60b2a79194993967a22paid10134245274EUR2020424EUR2017-03-15T21:20:36Z2017-03-15T21:20:36Z2017-03-15T21:20:36Z530048504502017-03-15T21:20:37Z0netautomaticusstCA0.0875true3c42a34e416c81f66c267d44a5b7d610invoicedSetup fee: Gold plangoldsetup_fee80011.1
070870EURfalseusstCA0.0875false2017-03-15T21:20:36Z2017-03-15T21:20:37Z2017-03-15T21:20:37Zevenlysizelarge
x-codeSamples:
- lang: PHP
source: |-
-
Lon Doner221B Baker St.LondonW1K 6AHGB421f7b7d414e4c6792938e7c49d552e9paid1005200002018-01-30T21:11:50Z0chargepurchase200001200EUR2020424USD2016-06-25T12:00:00ZusstCA00netautomatictrue
x-codeSamples:
- lang: PHP
source: |-
This API call will return the new invoice's details on success.
If there are no pending charges, it will return an HTTP status code of
`422 Unprocessable Entity`.
\ "
tags:
- invoices
operationId: postInvoiceInvoicePendingAdjustmentsOnAccount
parameters:
- in: path
required: true
name: account_code
schema:
$ref: "#/components/schemas/AccountCode"
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
terms_and_conditions:
type: string
default: ""
description:
Optional notes field. This will default to the Terms and Conditions
text specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Terms and Conditions. Custom notes will stay with a
subscription on all renewals.
customer_notes:
type: string
default: ""
description:
Optional notes field. This will default to the Customer Notes text
specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add Customer
Notes. Custom notes made on an invoice for a one time charge
will not carry over to subsequent invoices.
vat_reverse_charge_notes:
type: string
default: ""
description:
VAT Reverse Charge Notes only appear if you have EU VAT enabled or
are using your own Avalara AvaTax account and the customer
is in the EU, has a VAT number, and is in a different
country than your own. This will default to the VAT Reverse
Charge Notes text specified on the Tax Settings page in your
Recurly admin, unless custom notes were created with the
original subscription. Specify custom notes with this tag to
add or override VAT Reverse Charge Notes. Custom notes will
stay with a subscription on all renewals.
collection_method:
type: string
default: automatic
description: Can be either `automatic` or `manual`.
net_terms:
"$ref": "#/components/schemas/NetTerms"
net_terms_type:
"$ref": "#/components/schemas/NetTermsTypeEnum"
po_number:
type: string
default: ""
description:
Only supported with collection_method of `manual`. Optional notes
field. Attach a PO number to the invoice.
currency:
type: string
default: ""
description: The currency code for the currency used
vertex_transaction_type:
"$ref": "#/components/schemas/VertexTransactionTypeEnum"
responses:
"201":
description: ""
content:
application/xml:
example: >
123 Main St.San FranciscoCA94105US43adb97640cc05dee0b10042e596307fpending10164253425EUR2020424USD2018-03-19T15:43:41Z2018-03-19T15:43:41Z2018-03-20T15:43:41Z5000300002018-03-20T15:43:41Z0netmanualusstCA0.085true
"400":
description: Multiple Currencies
content:
application/xml:
example: >-
adjustments exist in multiple currencies
"422":
description: ""
content:
application/xml:
example: |-
will_not_invoiceNo adjustments to invoice
x-codeSamples:
- lang: xml
source: |-
manual
- lang: PHP
source: |-
-
account = Recurly::Account.find('1')
# invoice! takes invoice attributes as an optional argument
collection = account.invoice!(terms_and_conditions: 't and c', customer_notes: 'notes')
- lang: Python
source: >-
account = Account.get('1')
# invoice() takes invoice attributes as optional kwargs
collection = account.invoice(terms_and_conditions="t and c", customer_notes="notes")
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var newInvoice = new Invoice();
newInvoice.CollectionMethod = Invoice.Collection.Manual;
var invoiceCollection = account.InvoicePendingCharges(newInvoice);
var invoice = invoiceCollection.ChargeInvoice;
"/invoices/{invoice_number}/original_invoices":
get:
summary: List Original Invoices
description: |+
Given a credit invoice, list all charge invoices that were credited from it
tags:
- invoices
operationId: listOriginalInvoices
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
responses:
"200":
description: ""
content:
application/xml:
example: >-
ChickpeaLentil11060 US-31Elk RapidsMI49629US57d73e27d49d57e90d849d47ae8042b4paid101630530EUR2020424USD2020-12-15T22:08:49Z2020-12-15T22:13:31Z2020-12-15T22:08:49Z50050002020-12-15T22:08:49Z0chargepurchase30557d73e280791d83a0546474b53821583paymentUSD5302020-12-15T22:08:49Z2020-12-15T22:08:49Z0netautomaticusstMI0.06true30557d73e27ccf5acf411d12a4796990328invoicedChargedebit5001030530USDusstMI0.06false2020-12-15T00:00:00Z2020-12-15T22:08:49Z2020-12-15T22:13:31Zat_range_startsizelarge
x-codeSamples:
- lang: PHP
source: |-
original_invoices->get();
foreach ($original_invoices as $original_invoice) {
print "Original Invoice: $original_invoice\n";
}
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
credit_invoice = Recurly::Invoice.find('1018')
credit_invoice.original_invoices.find_each do |original_invoice|
puts "Invoice: #{original_invoice.inspect}"
end
- lang: Python
source: |-
credit_invoice = Invoice.get('1018')
for original_invoice in credit_invoice.original_invoices():
print 'Original Invoice: %s' % original_invoice
"/invoices/{invoice_number}/credit_invoices":
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
get:
summary: List Credit Invoices
description: |+
Given a charge invoice, list all credit invoices that were issued against it
tags:
- invoices
operationId: listCreditInvoices
responses:
"200":
description: ""
content:
application/xml:
example: >-
ChickpeaLentil11060 US-31Elk RapidsMI49629US57d7416d43238e5e187ab64e6c802715open1017-6-100EUR2020424USD2020-12-15T22:12:24Z2020-12-15T22:12:24Z-94-940-100creditrefundusstMI0.06true57d7416d375d461859c4db45c28ceca8invoicedChargedebit-941157d73e27ccf5acf411d12a47969903280-6-100USDusstMI0.06origindestinationfalse2020-12-15T00:00:00Z2020-12-15T22:12:24Z2020-12-15T22:12:24Zat_range_startrefundsizelarge
x-codeSamples:
- lang: PHP
source: |-
credit_invoices->get();
foreach ($credit_invoices as $credit_invoice) {
print "Credit Invoice: $credit_invoice\n";
}
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1016')
invoice.credit_invoices.find_each do |credit_invoice|
puts "Credit Invoice: #{credit_invoice.inspect}"
end
- lang: Python
source: |-
invoice = Invoice.get('1016')
for credit_invoice in invoice.credit_invoices():
print 'Credit Invoice: %s' % original_invoice
"/accounts/{account_code}/invoices/preview":
post:
summary: Preview Invoice
description: "Preview allows you to display the invoice details, including
estimated tax, before you post it.
This API call will return the new invoice's details on success.
If there are no pending charges, it will return an HTTP status code of
`422 Unprocessable Entity`.
\ "
tags:
- invoices
operationId: previewInvoice
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
terms_and_conditions:
type: string
default: ""
description:
Optional notes field. This will default to the Terms and Conditions
text specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Terms and Conditions. Custom notes will stay with a
subscription on all renewals.
customer_notes:
type: string
default: ""
description:
Optional notes field. This will default to the Customer Notes text
specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add Customer
Notes. Custom notes made on an invoice for a one time charge
will not carry over to subsequent invoices.
vat_reverse_charge_notes:
type: string
default: ""
description:
VAT Reverse Charge Notes only appear if you have EU VAT enabled or
are using your own Avalara AvaTax account and the customer
is in the EU, has a VAT number, and is in a different
country than your own. This will default to the VAT Reverse
Charge Notes text specified on the Tax Settings page in your
Recurly admin, unless custom notes were created with the
original subscription. Specify custom notes with this tag to
add or override VAT Reverse Charge Notes. Custom notes will
stay with a subscription on all renewals.
collection_method:
type: string
default: automatic
description: Can be either `automatic` or `manual`.
net_terms:
"$ref": "#/components/schemas/NetTerms"
net_terms_type:
"$ref": "#/components/schemas/NetTermsTypeEnum"
po_number:
type: string
default: ""
description: Optional notes field. Attach a PO number to the invoice.
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US43adb84ff8e763a22adb7542858f41fcpending4253425USD2018-03-20T15:42:26Z5000300002018-03-20T15:42:26Z0netmanualusstCA0.085true
"422":
description: ""
content:
application/xml:
example: |-
will_not_invoiceNo charges to invoice
x-codeSamples:
- lang: xml
source: |-
manual
- lang: PHP
source: |-
-
Lookup an invoice to retrieve detailed information about its line items
and payments.
**PAYMENTS**
Recurly returns an array of payments applied to an Invoice. At the moment, there is usually only one successful payment per invoice. The API only returns successful payments—it does not return failed payment attempts on an invoice nor does it return refunds on payments made to an invoice.
tags:
- invoices
operationId: lookupInvoice
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number. When using invoice number prefixes or country sequencing, include in the search params e.g. `TEST-1001`, `TEST-FR1001`, `FR1001`, `1001`.
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105USLon Doner221B Baker St.LondonW1K 6AHGB37c0057d2f641f4e2fcbda4b5b833633paidTEST-1007200002018-01-30T21:11:50Z0chargepurchase20004245274EUR2020424EUR2016-08-03T16:26:26Z2016-08-03T16:26:26Z2016-08-03T16:26:26ZusstCA0.08750netautomatictrue
x-codeSamples:
- lang: PHP
source: |-
+
This endpoint allows you to edit an existing invoice without changing
the line items or totals.
tags:
- invoices
operationId: editInvoice
parameters:
- in: path
required: true
name: invoice_number
schema:
type: string
default: ""
description: The invoice number for the invoice you wish to edit.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
po_number:
type: string
default: ""
description:
Optional purchase order number. Only allowed if type is charge or
(type is legacy and origin purchase).
customer_notes:
type: string
default: ""
description: Optional notes to be displayed to the customer on the invoice.
terms_and_conditions:
type: string
default: ""
description:
Optional terms and conditions to be displayed to the customer on
the invoice.
vat_reverse_charge_notes:
type: string
default: ""
description:
Optional VAT reverse charge notes to be displayed on the invoice.
Only allowed if invoice is a reverse charge case.
address:
type: object
default: ""
description: An address object representing the updated address details.
net_terms:
type: integer
default: ""
description: Optional net terms for the invoice collection.
gateway_code:
type: string
default: ""
description:
An alphanumeric code shown per gateway on your site's payment
gateways page. Set this code to ensure that a given invoice
targets a given gateway.
responses:
"200":
description: ""
content:
application/xml:
example: >-
VerenaExampleVerena ExampleVerena Example LLC.123 Main St.San FranciscoCA94105US43adb84ff8e763a22adb7542858f41fcpending601905000EUR2020424USD2018-07-13T17:13:57Z2018-07-13T17:13:57Z2018-07-14T17:13:57Z5000500002018-07-14T17:13:57Z5000chargepurchase5000manualabcde1234530false
x-codeSamples:
- lang: xml
source: >-
VerenaExampleVerena ExampleVerena Example LLC.123 Main St.San FranciscoCA94105US30abcde12345
- lang: PHP
source: |-
client);
$invoice->address = new Recurly_Address();
$invoice->address->first_name = "Verena";
$invoice->address->last_name = "Example";
$invoice->address->name_on_account = 'Verena Example';
$invoice->address->company = 'Verena Example LLC.';
$invoice->address->address1 = '123 Main St.';
$invoice->address->city = 'San Francisco';
$invoice->address->state = 'CA';
$invoice->address->zip = '94105';
$invoice->address->country = 'US';
$invoice->net_terms = '30';
$invoice->gateway_code = 'abcde12345'
$invoice->update();
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find(1000)
invoice.address = Recurly::Address.new(
first_name: "Verena",
last_name: "Example",
name_on_account: "Verena Example",
company: "Verena Example LLC.",
address1: "123 Main St.",
city: "San Francisco",
state: "CA",
country: "US",
zip: "94105"
)
invoice.net_terms = 30
invoice.gateway_code = abcde12345
invoice.save()
- lang: Python
source: |-
invoice = recurly.Invoice.get("1000")
invoice.address = recurly.Address(
first_name = 'Verena',
last_name = 'Example',
company = 'Verena Example LLC.',
name_on_account = 'Verena Example',
address1 = '123 Main St.',
city = 'San Francisco',
state = 'CA',
zip = '94105',
country = 'US',
)
invoice.net_terms = 30
invoice.gateway_code = abcde12345
invoice.save()
- lang: Dotnet
source: |-
var invoice = Invoice.get(1005);
var address = new Address();
address.FirstName = "Verena";
address.LastName = "Example";
address.Company = "Verena Example LLC.";
address.Address1 = "123 Main St.";
address.City = "San Francisco";
address.State = "CA";
address.Zip = "94105";
address.Country = "US";
invoice.Address = address;
invoice.NetTerms = 30;
invoice.GatewayCode = "abcde12345";
invoice.Update();
"/invoices/{invoice_number}/mark_successful":
put:
summary: Mark Invoice as Paid Successfully
description: "\n\n"
tags:
- invoices
operationId: markInvoiceAsPaidSuccessfully
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
responses:
"200":
description: ""
content:
application/xml:
example: >
123 Main St.San FranciscoCA94105US43adc17d4c4081556b317a460882b037paid10174255425EUR2020424USD2018-03-19T15:52:27Z2018-03-19T15:55:19Z2018-03-19T15:55:19Z5000500002018-03-20T15:52:27Z0netmanualusstCA0.085true
x-codeSamples:
- lang: PHP
source: |-
markSuccessful();
print "Invoice: $invoice";
} catch (Recurly_ValidationError $e) {
print "Could not mark paid: $e";
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1402')
invoice.mark_successful
- lang: Python
source: |-
invoice = Invoice.get('1402')
invoice.mark_successful()
- lang: Dotnet
source: |-
var invoice = Invoices.Get(1005);
invoice.MarkSuccessful();
"/invoices/{invoice_number}/mark_failed":
put:
summary: Mark Invoice as Failed Collection
description: "\n\n"
tags:
- invoices
operationId: markInvoiceAsFailedCollection
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US43adc4d7f16472f5b4a38e40148d44e6failed10184255425EUR2020424USD2018-03-19T15:56:07Z2018-03-19T15:56:17Z2018-03-19T15:56:17Z5000500002018-03-20T15:56:07Z0netmanualusstCA0.085true
x-codeSamples:
- lang: PHP
source: |-
markFailed();
print "Invoice: $collection";
} catch (Recurly_ValidationError $e) {
print "Could not mark failed: $e";
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('e3f0a9e084a2468480d00ee61b090d4d')
collection = invoice.mark_failed
- lang: Python
source: |-
invoice = Invoice.get('e3f0a9e084a2468480d00ee61b090d4d')
collection = invoice.mark_failed()
- lang: Dotnet
source: |-
var invoice = Invoices.Get(1005);
var collection = invoice.MarkFailed();
"/invoices/{invoice_number}/refund":
post:
summary: Refund/Void Line Items
description: |
Apply a refund to one or more individual line items on an invoice. A line item can be refunded by a quantity amount, a specific dollar/cent amount, or a percentage amount and will only apply to the specific line item you are aiming to refund.
* Note: You must have the Credit Memos feature flag enabled on your site to utilize specific dollar/cent amount and percentage amount refunds on line items.
An invoice with a processed line item refund cannot accept
refunds of an open amount.
This endpoint will not void an ACH bank account transaction. ACH
voids are only allowed through the UI.
tags:
- invoices
operationId: refundVoidLineItems
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- uuid
properties:
uuid:
type: string
default: ""
description: Adjustment's unique identifier.
quantity:
type: integer
default: ""
description:
Quantity to refund. Must be less than or equal to the
`quantity_remaining`. If `quantity_decimal`, `amount_in_cents`, and
`percentage` are not present, `quantity` is required. If
`amount_in_cents`, or `percentage` is present, `quantity` must be absent.
quantity_decimal:
type: string
default: ""
description:
Decimal quantity to refund. The `quantity_decimal` will be used to refund
charges that has a NOT null quantity decimal. Must be less than or equal to the
`quantity_decimal_remaining`. If `quantity`, `amount_in_cents`, and `percentage`
are not present, `quantity_decimal` is required. If `amount_in_cents` or `percentage`
is present, `quantity_decimal` must be absent. The Decimal Quantity feature must be
enabled to utilize this field.
amount_in_cents:
type: integer
default: ""
description:
The specific amount to be refunded from the adjustment. Must be less
than or equal to the adjustment's remaining balance. If `quantity`, `quantity_decimal`,
and `percentage` are not present, `amount_in_cents` is required. If `quantity`,
`quantity_decimal`, or `percentage` is present, `amount_in_cents` must be absent.
percentage:
type: integer
default: ""
description:
The percentage of the adjustment's remaining balance to refund. If
`quantity`, `quantity_decimal`, and `amount_in_cents` are not present, `percentage`
is required. If `quantity`, `quantity_decimal`, or `amount_in_cents` is present,
`percentage` must be absent.
minimum: 1
maximum: 100
prorate:
type: boolean
default: ""
description:
Toggle to prorate the line item to refund. Set as `true` or
`false`. Only applicable to subscription line items still in
the current billing cycle. Proration is not allowed on
invoices with an associated transaction that has not
settled, due to the full amount needed in order to void the
transaction.
refund_method:
type: string
default: credit_first
description:
If credit line items exist on the invoice, this parameter specifies
which refund method to use first. Most relevant in a partial
refunds, you can chose to refund credit back to the account
first or a transaction giving money back to the customer
first. If not specified, the default is credit back to the
account. Set as `credit_first`, `transaction_first`,
`all_transaction`, or `all_credit`.
external_refund:
type: boolean
default: ""
description: Designates that the refund transactions created are manual.
credit_customer_notes:
type: string
default: ""
description: Adds notes to refund credit invoice.
payment_method:
type: string
default: ""
description:
Creates the manual transactions with this payment method. Allowed
if `external_refund` is true.
description:
type: string
default: ""
description:
Sets this value as the `transaction_note` on the manual
transactions created. Allowed if `external_refund` is true.
refunded_at:
type: string
default: ""
description:
Sets this value as the `collected_at` on the manual transactions
created. Allowed if `external_refund` is true.
responses:
"201":
description: ""
content:
application/xml:
example: >-
2bc3cf4cbe357b7525eac5424292b445paid1010-97710-9771EUR2020424GBP2014-12-16T21:32:16Z2014-12-16T21:32:16Z0netautomaticfalse2bc3cf4cb513049c6aec1b419c97b508invoicedRefund for Setup fee: IP Addressesipaddressessetup_fee900-1000-900GBPfalsefalse2014-12-16T18:49:41Z2014-12-16T21:32:16Z2bc3cf4cb615aea5540bb54d4c9fc814invoicedRefund for IP Addressesipaddressesplan8871-1000-8871GBPfalsefalse2014-12-16T21:32:16Z2015-01-16T18:49:41Z2014-12-16T21:32:16Z
x-codeSamples:
- lang: xml
source: |-
2bc33a7469dc1458f455634212acdcd61false2bc33a746a89d867df47024fd6b261b61truecredit_first
- lang: PHP
source: >-
line_items; // get line items
// use Recurly_Adjustment->toRefundAttributes() to
// turn the line items you want into refund objects
// you can optionally pass in `prorated` and `quantity`
$adjustments = array_map(
function($line_item) { return $line_item->toRefundAttributes(); },
$invoice->line_items
);
// pass the refund attributes to the refund() method
// returns a new Recurly_Invoice
$refund_invoice = $invoice->refund($adjustments, 'transaction_first');
$refund_invoice->subtotal_in_cents; // -1000
print "Refund Invoice: $refund_invoice";
} catch (Recurly_ValidationError $e) {
// There is a problem with the data or the invoice can't be refunded
print "Validation Error: $e";
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
// There is an alternative way to call refund directly on an adjustment
try {
// grab some adjustment
$adjustment = Recurly_Adjustment::get('2fe89a073a31318cab377e464cb811b4');
// you can optionally pass in the same arguments as toRefundAttributes
// return Recurly_Invoice
$refund_invoice = $adjustment->refund(null, false, 'all_credit');
$refund_invoice->subtotal_in_cents; // -1000
print "Refund Invoice: $refund_invoice";
} catch (Recurly_ValidationError $e) {
// There is a problem with the data or the invoice can't be refunded
print "Validation Error: $e";
} catch (Recurly_NotFoundError $e) {
print "Adjustment not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find(1005)
adjustments = invoice.line_items.map do |adjustment|
{ adjustment: adjustment, quantity: 1, prorate: false }
end
invoice.refund adjustments, 'credit_first'
- lang: Python
source: >-
invoice = Invoice.get('1005')
line_items = list({'adjustment' : adjustment, 'quantity' : 1, 'prorate' : False} for adjustment in invoice.line_items)
refund_invoice = invoice.refund(line_items, 'credit_first')
- lang: Dotnet
source: >-
// refund a single adjustment
var invoice = Invoices.Get(1005);
var adjustment = invoice.Adjustments.First(x => x.Uuid == "e1234245132465");
invoice = invoice.Refund(adjustment, false, 1); // adjustment, prorate, quantity
// refund multiple adjustments
var invoice = Invoices.Get(1005);
var refundOptions = new Invoice.RefundOptions() {
ExternalRefund = true,
Description = "External Refund Description",
CreditCustomerNotes = "Credit Customer Notes",
PaymentMethod = "credit_card",
Method = Invoice.RefundMethod.AllTransaction
};
invoice.Refund(invoice.Adjustments, refundOptions);
"/invoices/{invoice_number}/transactions":
post:
summary: Enter Offline Payment for Manual Invoice
description: >+
Allows you to enter an offline payment for a manual invoice, such as a
check or money order.
tags:
- invoices
operationId: enterOfflinePaymentForManualInvoice
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- payment_method
properties:
payment_method:
type: string
default: ""
description:
"The method of payment: `credit_card`, `paypal`, `amazon`, `roku`,
`ach`, `apple_pay`, `eft`, `wire_transfer`, `money_order`,
`check`, or `other`."
collected_at:
type: string
format: date-time
default: ""
description: Date payment was collected.
amount_in_cents:
type: integer
default: ""
description: The amount paid in cents.
description:
type: string
default: ""
description: Note for the manual payment. Max 50 characters.
responses:
"201":
description: ""
content:
application/xml:
example: >-
43adf00383b138ae7e56084dfe93eb9epurchase500EUR2020424USDsuccesschecktransactionfalsetruetruetrueapiPaid with a checkManually entered transaction2018-03-19T16:43:16Z2018-03-19T16:33:15Z2018-03-19T16:43:16Z1VerenaExampleNew Company Nameverena@example.comVerenaExample
schema:
$ref: "#/components/schemas/Transaction"
x-codeSamples:
- lang: xml
source: |-
check2018-03-19T10:33:16-06:0050Paid with a check'
- lang: PHP
source: >-
payment_method = 'check';
$transactionAttrs->collected_at = date('c', strtotime('2012-12-31Z'));
$transactionAttrs->amount_in_cents = 4;
$transactionAttrs->description = "check #12345";
$transaction = $invoice->enterOfflinePayment($transactionAttrs);
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1001')
invoice.enter_offline_payment(
:payment_method => 'check',
:amount_in_cents => 1000,
:description => 'Paid with check',
:collected_at => Time.utc(2015, 04, 25)
)
- lang: Python
source: >-
invoice = recurly.Invoice.get("1001")
transaction = recurly.Transaction(amount_in_cents=11, description="Collected externally")
transaction = invoice.enter_offline_payment(transaction)
- lang: Dotnet
source: >-
var account = new Account(System.Guid.NewGuid().ToString());
account.Create();
var adjustment = account.NewAdjustment("USD", 1000, "Test Charge");
adjustment.Create();
var newInvoice = new Invoice();
newInvoice.CollectionMethod = Invoice.Collection.Manual;
var invoice = account.InvoicePendingCharges(newInvoice).ChargeInvoice;
var offlineTransaction = new Transaction(account, 1000, "");
offlineTransaction.PaymentMethod = "check";
offlineTransaction.CollectedAt = new DateTime(2018, 12, 11, 0, 0, 0, DateTimeKind.Local);
offlineTransaction.Description = "Paid with check";
try
{
var recordedTransaction = invoice.EnterOfflinePayment(offlineTransaction);
Console.WriteLine(recordedTransaction.Status);
}
catch(ValidationException e)
{
Console.WriteLine(e);
foreach (var err in e.Errors) {
Console.WriteLine(err);
}
}
"/invoices/{invoice_number}/collect":
put:
summary: Collect an Invoice
description: >+
Allows to collect a past-due or pending invoice. This API is rate
limited and only one collection attempt per account is allowed within an
hour. This API endpoint is only available in API version 2.5 or higher.
tags:
- invoices
operationId: collectAnInvoice
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number to collect
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
transaction_type:
type: string
default: ""
description: 'Indicates type of resulting transaction. accepted_values: "moto".'
billing_info:
type: object
default: ""
description: Accepts nested three_d_secure_action_result_token_id (string)
billing_info_uuid:
type: string
description:
The `billing_info_uuid` is the value that represents a specific
billing info for an end customer. When `billing_info_uuid` is used to assign
billing info to the subscription, all future billing events for the subscription
will bill to the specified billing info. `billing_info_uuid` can ONLY be
used for sites utilizing the Wallet feature.
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US374a37924f83c733b9c9814e9580496apending100050004385438EUR2020424USD2016-07-11T19:25:57Z2016-07-11T19:25:57ZusstCA0.08750netautomatictrue
"400":
description: ""
content:
application/xml:
example: >-
# Rate Limit Hit
too_many_collection_attemptsOnly one force collection available per hour per invoiceunable_to_collectOnly pending or past due invoices can be collected.unable_to_collectManual invoices cannot be collected by Recurly.
x-codeSamples:
- lang: PHP
source: |-
billing_info_uuid = 'billingInfoUuid';
$invoice->forceCollect();
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1000')
invoice.billing_info_uuid = 'billingInfoUuid'
invoice.force_collect
- lang: Python
source: |-
invoice = recurly.Invoice.get('1000')
invoice.billing_info_uuid = 'billingInfoUuid'
invoice.force_collect()
- lang: Dotnet
source: |-
var invoice = Invoices.Get(1000);
invoice.BillingInfoUuid = "billingInfoUuid";
var collection = invoice.ForceCollect();
"/invoices/{invoice_number}/apply_credit_balance":
put:
summary: Apply available credit to a pending or past due charge invoice
description:
Apply credit payment to the outstanding balance on an existing
charge invoice from an account’s available balance from existing credit invoices.
tags:
- invoices
operationId: applyCreditBalance
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number for collectible charge invoice
responses:
"200":
description: ""
content:
application/xml:
example: >
123 Main St.San FranciscoCA94105US43adc17d4c4081556b317a460882b037paid10174255425EUR2020424USD2018-03-19T15:52:27Z2018-03-29T15:55:19Z2018-03-29T15:55:19Z5000500002018-03-30T15:52:27Z10netmanualusstCA0.085true3d3f6754c6df41b9d2a32e43029adc55paymentUSD54252018-03-29T15:52:27Z2018-03-29T15:52:27Z
"400":
description: Invoice wrong type/state or account has no available credit
content:
application/xml:
example: >-
unable_to_apply_creditCredit can only be applied to a pending or past due charge invoiceunable_to_apply_creditThere is not any available credit to apply
x-codeSamples:
- lang: PHP
source: |-
applyCreditBalance();
print "Invoice: $invoice";
} catch (Recurly_ValidationError $e) {
print "Could not apply credit balance: $e";
} catch (Recurly_NotFoundError $e) {
print "Invoice not found: $e";
}
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1017')
invoice.apply_credit_balance
- lang: Python
source: |-
invoice = Invoice.get('1017')
invoice.apply_credit_balance()
- lang: Dotnet
source: |-
var invoice = Invoices.Get(1017);
invoice.ApplyCreditBalance();
"/invoices/{invoice_number}/void":
put:
summary: Void a Credit Invoice
description: |+
Allows voiding a an open credit invoice
tags:
- invoices
operationId: voidACreditInvoice
parameters:
- in: path
name: invoice_number
schema:
type: string
default: ""
required: true
description: Invoice number to collect
responses:
"200":
description: ""
content:
application/xml:
example: >-
123 Main St.San FranciscoCA94105US374a37924f83c733b9c9814e9580496avoided100050004385438EUR2020424USD2016-07-11T19:25:57Z2016-07-11T19:25:57ZusstCA0.08750netautomatictrue
"400":
description: Rate limit failure
content:
application/xml:
example: >-
# Rate Limit Hit
too_many_collection_attemptsOnly one force collection available per hour per invoice
x-codeSamples:
- lang: PHP
source: |-
void();
- lang: Ruby
source: |-
invoice = Recurly::Invoice.find('1000')
invoice.void
- lang: Dotnet
source: |-
var invoice = Invoices.Get("1000");
invoice.Void();
"/plans":
get:
summary: List Plans
description: "Lists all your active subscription plans.
The client library will automatically fetch the next page of the
results. There may be a slight delay when fetching the next page.
\ "
tags:
- plans
operationId: listPlans
parameters:
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
schema:
type: array
items:
$ref: "#/components/schemas/Plan"
example: >-
platinumPlatinum planfalsefalsefalsefalseunit1months0days2016-08-02T16:48:34Z2016-08-02T16:48:34Zat_range_endat_range_startfalsetruesizelarge45000600008001000sale
x-codeSamples:
- lang: PHP
source: |-
plan_code = 'gold';
$plan->name = "Gold plan";
$plan->unit_amount_in_cents->addCurrency('USD', 1000); // USD 10.00 month
$plan->unit_amount_in_cents->addCurrency('EUR', 800); // EUR 8.00 month
$plan->setup_fee_in_cents->addCurrency('USD', 6000); // USD 60.00 setup fee
$plan->setup_fee_in_cents->addCurrency('EUR', 4500); // EUR 45.00 setup fee
$plan->plan_interval_length = 1;
$plan->plan_interval_unit = 'months';
$plan->tax_exempt = false;
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$new_plan->liability_gl_account_id = $liability_general_ledger_account_id;
$new_plan->revenue_gl_account_id = $revenue_general_ledger_account_id;
$new_plan->performance_obligation_id = $pob_id;
$new_plan->setup_fee_liability_gl_account_id = $setup_fee_liability_general_ledger_account_id;
$new_plan->setup_fee_revenue_gl_account_id = $setup_fee_revenue_general_ledger_account_id;
$new_plan->setup_fee_performance_obligation_id = $setup_fee_pob_id;
$plan->create();
print "Plan: $plan";
} catch (Recurly_ValidationError $e) {
print "Invalid Data: $e";
}
// ramp pricing
try {
$planCode = 'snarf-mcsnarfington-the-third';
$plan = new Recurly_Plan();
$plan->name = $planCode;
$plan->plan_code = $planCode;
$plan->setup_fee_in_cents->addCurrency('USD', 0);
// must have ramp_pricing feature flag enabled
$plan->pricing_model = 'ramp';
$ramp1 = new Recurly_PlanRampInterval(1);
$ramp1->unit_amount_in_cents['USD'] = 123;
$ramp2 = new Recurly_PlanRampInterval(3);
$ramp2->unit_amount_in_cents['USD'] = 456;
$ramp3 = new Recurly_PlanRampInterval(7);
$ramp3->unit_amount_in_cents['USD'] = 789;
array_push($plan->ramp_intervals, $ramp1, $ramp2, $ramp3);
$plan->create();
print("Plan:\n");
print($plan);
} catch(Recurly_Error $e) {
print("Caught an error:\n");
print($e);
}
- lang: Ruby
source: |-
# fixed pricing
plan = Recurly::Plan.create(
:plan_code => 'gold',
:name => 'Gold plan',
:unit_amount_in_cents => { 'USD' => 10_00, 'EUR' => 8_00 },
:setup_fee_in_cents => { 'USD' => 60_00, 'EUR' => 45_00 },
:plan_interval_length => 1,
:plan_interval_unit => 'months'
:tax_exempt => false,
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
liability_gl_account_id: liability_gl_account.id,
setup_fee_liability_gl_account_id: setup_fee_liability_gl_account.id,
revenue_gl_account_id: revenue_gl_account.id,
setup_fee_revenue_gl_account_id: setup_fee_revenue_gl_account.id,
setup_fee_performance_obligation_id: setup_fee_pob.id,
performance_obligation_id: pob.id,
)
# ramp pricing
plan = Recurly::Plan.create!(
{
plan_code: 'gold',
name: 'Gold Plan',
setup_fee_in_cents: { 'USD': 60_00 },
plan_interval_unit: 'months',
tax_exempt: false,
pricing_model: 'ramp',
ramp_intervals: [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 1000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 2000
}
)
]
}
)
- lang: Python
source: |-
# fixed pricing
plan = Plan(plan_code='gold', name='Gold plan')
plan.unit_amount_in_cents = Money(USD=1000, EUR=800)
plan.setup_fee_in_cents = Money(USD=6000, EUR=4500)
plan.plan_interval_length = 1
plan.plan_interval_unit = 'months'
plan.tax_exempt = False
plan.save()
print(f'Plan: {plan}')
# ramp pricing
ramp_interval_1 = recurly.PlanRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=recurly.Money(USD=2000)
)
ramp_interval_2 = recurly.PlanRampInterval(
starting_billing_cycle=2,
unit_amount_in_cents=recurly.Money(USD=3000)
)
plan_code = 'awesome-ramp-plan-2234'
plan = recurly.Plan(plan_code=plan_code, name=f'{plan_code}')
plan.setup_fee_in_cents = recurly.Money(USD=6000)
plan.plan_interval_unit = 'months'
plan.tax_exempt = False
plan.pricing_model = 'ramp'
plan.ramp_intervals = [ramp_interval_1, ramp_interval_2]
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
plan.liability_gl_account_id = liability_gl_account_id
plan.revenue_gl_account_id = revenue_gl_account_id
plan.performance_obligation_id = performance_obligation_id
plan.setup_fee_liability_gl_account_id = setup_fee_liability_gl_account_id
plan.setup_fee_revenue_gl_account_id = setup_fee_revenue_gl_account_id
plan.setup_fee_performance_obligation_id = setup_fee_performance_obligation_id
plan.save()
print(f'Plan: {plan}')
- lang: Dotnet
source: |-
// fixed pricing
var plan = new Plan("gold", "Gold plan"); // plan code, name
plan.UnitAmountInCents.Add("USD", 1000);
plan.UnitAmountInCents.Add("EUR", 800);
plan.SetupFeeInCents.Add("USD", 6000);
plan.SetupFeeInCents.Add("EUR", 4500);
plan.PlanIntervalLength = 1;
plan.PlanIntervalUnit = Plan.IntervalUnit.Months;
plan.TaxExempt = false;
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
plan.LiabilityGlAccountId = baseFeeLiabilityGlaId;
plan.RevenueGlAccountId = baseFeeRevenueGlaId;
plan.PerformanceObligationId = baseFeePerformanceObligationId;
plan.SetupFeeLiabilityGlAccountId = setupFeeLiabilityGlaId;
plan.SetupFeeRevenueGlAccountId = setupFeeRevenueGlaId;
plan.SetupFeePerformanceObligationId = setupFeePerformanceObligationId;
plan.Create();
// ramp pricing
var plan = new Plan("gold", "Gold plan"); // plan code, name
plan.PricingModel = PricingModelType.Ramp;
// Building a pricing schedule with 2 ramp intervals
plan.RampIntervals = new List
{
new PlanRampInterval()
{
StartingBillingCycle = 1,
Currencies = new List // Build the list of currencies for the ramp interval
{
// When building the Currencies list, you may add as many currencies as your site supports
new PlanRampPricing()
{
Currency = "USD",
UnitAmountInCents = 500
}
}
},
new PlanRampInterval()
{
StartingBillingCycle = 3,
Currencies = new List
{
new PlanRampPricing()
{
Currency = "USD",
UnitAmountInCents = 1000
}
}
}
};
// Create the plan
plan.Create();
- lang: Java
source: |-
final Plan plan = new Plan();
plan.setPlanCode("planCode");
plan.setName("Generic Plan");
final RecurlyUnitCurrency price = new RecurlyUnitCurrency();
price.setUnitAmountUSD(10);
plan.setUnitAmountInCents(price);
plan.setAutoRenew(false);
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
plan.setLiabilityGlAccountId(liabilityGlaId);
plan.setSetupFeeLiabilityGlAccountId(liabilityGlaId);
plan.setRevenueGlAccountId(revenueGlaId);
plan.setSetupFeeRevenueGlAccountId(revenueGlaId);
plan.setPerformanceObligationId(pobId);
plan.setSetupFeePerformanceObligationId(pobId);
final Plan planResponse = client.createPlan(plan);
System.out.println("Plan created: " + planResponse);
"/plans/{plan_code}":
parameters:
- $ref: "#/components/parameters/plan_code"
get:
summary: Lookup Plan
description: |+
Lookup a plan's details.
tags:
- plans
operationId: lookupPlan
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Plan"
examples:
fixedPricing:
$ref: "#/components/examples/PlanFixedPricingResponse"
rampPricing:
$ref: "#/components/examples/PlanRampPricingResponse"
x-codeSamples:
- lang: PHP
source: |-
+
Update the pricing or details for a plan. Existing subscriptions will
remain at the previous renewal amounts.
tags:
- plans
operationId: updatePlan
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/PlanUpdate"
examples:
fixedPricing:
$ref: "#/components/examples/PlanFixedPricingRequest"
rampPricing:
$ref: "#/components/examples/PlanRampPricingRequest"
revRec:
$ref: "#/components/examples/PlanWithRevRecRequest"
responses:
"200":
$ref: "#/components/responses/PlanCreateUpdate"
x-codeSamples:
- lang: PHP
source: |-
unit_amount_in_cents['EUR'] = 5000; // EUR 50.00 monthly fee
$plan->setup_fee_in_cents['EUR'] = 5000; // EUR 50.00 setup fee
$plan->update();
print "Plan: $plan";
} catch (Recurly_ValidationError $e) {
print "Invalid Data: $e";
} catch (Recurly_NotFoundError $e) {
print "Plan Not Found: $e";
}
// ramp pricing
try {
$plan = Recurly_Plan::get('gold_ramp_pricing');
$newRamp = new Recurly_PlanRampInterval(5);
$newRamp->unit_amount_in_cents['USD'] = 777;
$plan->ramp_intervals[2]->unit_amount_in_cents['USD'] = 999;
array_splice($plan->ramp_intervals, -1, 0, array($newRamp));
$plan->update();
print("EDITED Plan: $plan->name" . PHP_EOL);
print($plan . PHP_EOL);
} catch(Recurly_Error $e) {
print("Caught an error:" . PHP_EOL);
print($e . PHP_EOL);
}
// Recurly RevRec Standard/Advanced (RA-Managed)
try {
$plan = Recurly_Plan::get('gold_rev_rec');
$plan->performance_obligation_id = $new_pob_id;
$plan->setup_fee_performance_obligation_id = $new_setup_fee_pob_id;
$plan->liability_gl_account_id = $new_liability_gla_id;
$plan->revenue_gl_account_id = $new_revenue_gla_id;
$plan->setup_fee_liability_gl_account_id = $new_setup_fee_liability_gla_id;
$plan->setup_fee_revenue_gl_account_id = $new_setup_fee_revenue_gla_id;
- lang: Ruby
source: |-
# fixed pricing
plan = Recurly::Plan.find('gold')
plan.setup_fee_in_cents['EUR'] = 50_00
plan.save
# ramp pricing
plan = Recurly::Plan.find('gold-ramped-plan')
plan.ramp_intervals = [
Recurly::PlanRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: {
USD: 5000
}
),
Recurly::PlanRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: {
USD: 100_00
}
)
]
plan.save!
# Recurly RevRec Standard/Advanced (RA-Managed)
plan = Recurly::Plan.find('revrec-plan')
plan.revenue_gl_account_id = revenue_gl_account.id
plan.liability_gl_account_id = liability_gl_account.id
plan.setup_fee_performance_obligation_id = new_pob.id
plan.setup_fee_revenue_gl_account_id = setup_fee_revenue_gl_account.id
plan.setup_fee_liability_gl_account_id = setup_fee_liability_gl_account.id
plan.performance_obligation_id = new_pob.id
plan.save!
- lang: Python
source: |-
# fixed pricing
plan = Plan.get('gold')
plan.setup_fee_in_cents['EUR'] = 5000
plan.save()
# ramp pricing
plan = Plan.get('gold-ramped-plan')
ramp_interval_1 = recurly.PlanRampInterval(
starting_billing_cycle=1,
unit_amount_in_cents=recurly.Money(USD=5000)
)
ramp_interval_2 = recurly.PlanRampInterval(
starting_billing_cycle=2,
unit_amount_in_cents=recurly.Money(USD=6000)
)
plan.ramp_intervals = [ramp_interval_1, ramp_interval_2]
plan.save()
# Recurly RevRec Standard/Advanced (RA-Managed)
plan = Plan.get('gold')
plan.liability_gl_account_id = liability_gl_account_id
plan.revenue_gl_account_id = revenue_gl_account_id
plan.performance_obligation_id = performance_obligation_id
plan.setup_fee_liability_gl_account_id = setup_fee_liability_gl_account_id
plan.setup_fee_revenue_gl_account_id = setup_fee_revenue_gl_account_id
plan.setup_fee_performance_obligation_id = setup_fee_performance_obligation_id
plan.save()
print(f'Plan: {plan}')
- lang: Dotnet
source: |-
// fixed pricing
var plan = Plans.Get("gold");
plan.SetupFeeInCents["EUR"] = 5000;
plan.Update();
// ramp pricing
plan = Plans.Get("gold-ramped-plan");
plan.RampIntervals[1].StartingBillingCycle = 2;
plan.Update();
// Recurly RevRec Standard/Advanced (RA-Managed)
plan = Plans.Get("gold");
plan.LiabilityGlAccountId = newBaseFeeLiabilityGlaId;
plan.RevenueGlAccountId = newBaseFeeRevenueGlaId;
plan.PerformanceObligationId = newBaseFeePerformanceObligationId;
plan.SetupFeeLiabilityGlAccountId = newSetupFeeLiabilityGlaId;
plan.SetupFeeRevenueGlAccountId = newSetupFeeRevenueGlaId;
plan.SetupFeePerformanceObligationId = newSetupFeePerformanceObligationId;
plan.Update();
- lang: Java
source: |-
final Plan plan = client.getPlan("sliver");
// Recurly RevRec Standard/Advanced (RA-Managed)
// PerformanceObligationId will be set to the default if omitted,
// but can be explicitly set if desired.
plan.setPerformanceObligationId(newPobId);
plan.setSetupFeePerformanceObligationId(newPobId);
// will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
plan.setLiabilityGlAccountId(newLiabilityGlaId);
plan.setSetupFeeLiabilityGlAccountId(newLiabilityGlaId);
plan.setRevenueGlAccountId(newRevenueGlaId);
plan.setSetupFeeRevenueGlAccountId(newRevenueGlaId);
final Plan updatedPlan = client.updatePlan(plan);
System.out.println("Plan updated: " + updatedPlan);
delete:
summary: Delete Plan
description: >+
Deleting a plan makes it inactive. New subscriptions cannot be created
from the plan.
tags:
- plans
operationId: deletePlan
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
delete();
print "Plan: $plan";
} catch (Recurly_NotFoundError $e) {
print "Plan Not Found: $e";
}
- lang: Ruby
source: |-
plan = Recurly::Plan.find('gold')
plan.destroy
- lang: Python
source: |-
plan = Plan.get('gold')
plan.delete()
- lang: Dotnet
source: |-
var plan = Plans.Get("gold");
plan.Deactivate();
"/items":
get:
summary: List Items
description: "Lists all your items in the catalog.
The client library will automatically fetch the next page of the
results. There may be a slight delay when fetching the next page.
\ "
tags:
- items
operationId: listItems
parameters:
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
schema:
type: array
items:
$ref: "#/components/schemas/Item"
example: >-
pink_sweatersPink SweatersFavorite Pink SweatersPS1234ps0000193evenlyfalseactivesizelargety4utwr0mrgztwyyzw8vcm367ps2019-11-21T15:55:19Z2019-11-21T15:55:19Z
x-codeSamples:
- lang: PHP
source: |-
name\n";
}
- lang: Ruby
source: |-
Recurly::Item.find_each do |item|
puts "Item: #{item.name}"
end
- lang: Python
source: |-
#client version 2.1.6+
for item in recurly.Item.all():
print(f'Item: {item.name}')
#client version <= 2.1.5
items = Item.all()
while items:
for item in items:
print 'Item: %s' % item
try:
items = items.next_page()
except PageError:
items = ()
- lang: Dotnet
source: |-
using System.Linq;
var items = Items.List();
while (items.Any())
{
foreach (var item in items)
Console.WriteLine("Item: " + item.Name);
items = items.Next;
}
post:
summary: Create Item
description: |+
Create a new item in the catalog.
tags:
- items
operationId: createItem
parameters: []
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- item_code
- name
properties:
item_code:
type: string
default: ""
description: Unique code to identify the item. Max of 50 characters.
name:
type: string
default: ""
description: Item name. Max of 255 characters.
description:
type: string
default: ""
description: Optional plan description, not displayed.
external_sku:
type: string
default: ""
description:
Stock keeping unit to link the item to other inventory. Max of 50
characters.
accounting_code:
type: string
default: ""
description:
"Accounting code for invoice line items. Code may only contain the
following characters: [a-z 0-9 @ - _ .]. Max of 20
characters."
revenue_schedule_type:
type: string
default: evenly
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Item should be
recognized. Available schedule types are never, evenly,
at_range_start, or at_range_end.
state:
type: string
default: ""
description:
The current state of the item. Will be either active or inactive.
Read-only.
custom_fields:
$ref: "#/components/schemas/CustomFields"
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
responses:
"201":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Item"
example: >-
pink_sweatersPink SweatersFavorite Pink SweatersPS1234ps0000193evenlyfalseactivesizelargety4utwr0mrgztwyyzw8vcm367ps2019-11-21T15:55:19Z2019-11-21T15:55:19Z
x-codeSamples:
- lang: xml
source: |-
pink_sweatersPink SweatersFavorite Pink SweatersPS1234ps0000193evenlysizelargety4utwr0mrgztwyyzw8vcm367ps
- lang: PHP
source: |-
item_code = 'pink_sweaters';
$item->name = 'Pink Sweaters';
$item->description = 'Favorite Pink Sweaters';
$item->external_sku = 'PS1234';
$item->custom_fields[] = new Recurly_CustomField('size', 'large');
// legacy revenue recognition
$item->accounting_code = 'ps0000193';
$item->revenue_schedule_type = 'evenly';
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$item->performance_obligation_id = $my_pob_id;
$item->revenue_gl_account_id = $my_revenue_gla_id;
$item->liability_gl_account_id = $my_liability_gla_id;
$item->create();
print "Item: item";
} catch (Recurly_ValidationError $e) {
print "Invalid Data: $e";
}
- lang: Ruby
source: >-
item = Recurly::Item.create!(
item_code: 'pink_sweaters',
name: 'Pink Sweaters',
description: 'Favorite Pink Sweaters',
external_sku: 'PS1234',
custom_fields: [Recurly::CustomField.new(name: 'size', value: 'large')],
# legacy revenue recognition
accounting_code: 'ps0000193',
revenue_schedule_type: 'evenly',
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
liability_gl_account_id: liability_gl_account.id,
revenue_gl_account_id: revenue_gl_account.id,
performance_obligation_id: pob.id
)
- lang: Python
source: >-
item = recurly.Item(
item_code = 'pink_sweaters',
name = 'Pink Sweaters',
description = 'Favorite Pink Sweaters',
external_sku = 'PS1234',
accounting_code = 'ps0000193',
revenue_schedule_type = 'evenly',
custom_fields = [recurly.CustomField(name = 'size', value = 'large')],
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
liability_gl_account_id = liability_gl_account_id,
revenue_gl_account_id = revenue_gl_account_id,
performance_obligation_id = performance_obligation_id
)
item.save()
- lang: Dotnet
source: |-
var item = new Item("pink_sweaters", "Pink Sweaters"); // item code,
name
item.Description = "Favorite Pink Sweaters";
item.ExternalSku = "PS1234";
// legacy revenue recognition
item.AccountingCode = "ps0000193";
item.RevenueScheduleType = "evenly";
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
item.LiabilityGlAccountId = liabilityGlaId;
item.RevenueGlAccountId = revenueGlaId;
item.PerformanceObligationId = performanceObligationId;
item.CustomFields.Add(new CustomField("size", "large"));
item.Create();
- lang: Java
source: |-
final Item item = new Item();
item.setItemCode("itemCode");
item.setName("Tree Fiddy");
// Recurly RevRec Standard/Advanced (RA-Managed)
item.setLiabilityGlAccountId(liabilityGlaId);
item.setRevenueGlAccountId(revenueGlaId);
item.setPerformanceObligationId(pobId);
client.createItem(item);
"/items/{item_code}":
get:
summary: Lookup Item
description: |+
Lookup an item's details.
tags:
- items
operationId: lookupItem
parameters:
- in: path
name: item_code
schema:
type: string
default: ""
required: true
description: Unique code to identify the item.
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Item"
example: >-
pink_sweatersPink SweatersFavorite Pink SweatersPS1234ps0000193evenlyfalseactivesizelargety4utwr0mrgztwyyzw8vcm367ps2019-11-21T15:55:19Z2019-11-21T15:55:19Z
x-codeSamples:
- lang: PHP
source: |-
-
pink_sweatersPink SweatersSecond-Favorite Pink SweatersPS1234ps0000193evenlyfalseactivesizelargety4utwr0mrgztwyyzw8vcm367ps2019-11-21T15:55:19Z2019-11-21T15:55:19Z
x-codeSamples:
- lang: xml
source: |-
pink_sweatersSecond-Favorite Pink Sweatersty4utwr0mrgztwyyzw8vcm367ps
- lang: PHP
source: |-
description = 'Second-Favorite Pink Sweaters';
// Recurly RevRec Standard/Advanced (RA-Managed)
$item->revenue_gl_account_id = $new_revenue_gla_id;
$item->liability_gl_account_id = $new_liability_gla_id;
$item->performance_obligation_id = $new_pob_id;
$item->update();
print "Item: item";
} catch (Recurly_ValidationError $e) {
print "Invalid Data: $e";
}
- lang: Ruby
source: |-
item = recurly.Item.get('pink_sweaters')
item.update_attributes(
description: "Second-Favorite Pink Sweaters",
# Recurly RevRec Standard/Advanced (RA-Managed)
liability_gl_account_id: updated_liability_gl_account.id,
revenue_gl_account_id: updated_revenue_gl_account.id,
performance_obligation_id: updated_pob.id
)
- lang: Python
source: |-
item = recurly.Item.get('pink_sweaters')
item.description = 'Second-Favorite Pink Sweaters',
# Recurly RevRec Standard/Advanced (RA-Managed)
item.liability_gl_account_id = liability_gl_account_id,
item.revenue_gl_account_id = revenue_gl_account_id,
item.performance_obligation_id = performance_obligation_id
item.save()
- lang: Dotnet
source: |-
var item = Items.Get("pink_sweaters");
item.Description = "Second-Favorite Pink Sweaters";
// Recurly RevRec Standard/Advanced (RA-Managed)
item.LiabilityGlAccountId = liabilityGlaId;
item.RevenueGlAccountId = revenueGlaId;
item.PerformanceObligationId = performanceObligationId;
item.Update();
- lang: Java
source: |-
final Item item = client.getItem("updatable_item")
// Recurly RevRec Standard/Advanced (RA-Managed)
item.setLiabilityGlAccountId(liabilityGlaId);
item.setRevenueGlAccountId(revenueGlaId);
item.setPerformanceObligationId(pobId);
final Item updatedItem = client.updateItem(item.getItemCode(), item);
delete:
summary: Deactivate Item
description: |+
Deactivating a item makes it inactive.
tags:
- items
operationId: deactivateItem
parameters:
- in: path
name: item_code
schema:
type: string
default: ""
required: true
description: Unique code to identify the item.
responses:
"204":
description: ""
content:
application/xml:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: |-
delete();
print "Item: $item";
} catch (Recurly_NotFoundError $e) {
print "Item Not Found: $e";
}
- lang: Ruby
source: |-
item = Recurly::Item.find('pink_sweaters')
item.destroy
- lang: Python
source: |-
item = Item.get('pink_sweaters')
item.delete()
- lang: Dotnet
source: |-
var item = Items.Get("pink_sweaters");
item.Deactivate();
"/items/{item_code}/reactivate":
put:
summary: Reactivate Item
description: |+
Reactivate an inactive item.
tags:
- items
operationId: reactivateItem
parameters:
- in: path
name: item_code
schema:
type: string
default: ""
required: true
description: Unique code to identify the item.
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Item"
example: >-
pink_sweatersPink SweatersFavorite Pink SweatersPS1234ps0000193evenlyfalseactivesizelarge2019-11-21T15:55:19Z2019-11-21T15:55:19Z
x-codeSamples:
- lang: PHP
source: |-
reactivate();
print "Item: $item";
} catch (Recurly_NotFoundError $e) {
print "Item Not Found: $e";
}
- lang: Ruby
source: |-
item = Recurly::Item.find('pink_sweaters')
item.reactivate
- lang: Python
source: |-
item = Item.get('pink_sweaters')
item.reactivate()
- lang: Dotnet
source: |-
var item = Items.Get("pink_sweaters");
item.Reactivate();
"/plans/{plan_code}/add_ons":
parameters:
- $ref: "#/components/parameters/plan_code"
get:
summary: List Plan's Add-Ons
description: |+
Returns a list of all the add-ons for a plan.
tags:
- plan-add-ons
operationId: listPlansAddOns
parameters:
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: path
name: plan_code
schema:
type: string
required: true
description: Plan Code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
video_streamingVideo Streaming1false4550usagetruepriceevenly2016-08-03T15:25:09Z2016-08-03T15:25:09Zty4utwr0mrgztwyyzw8vcm367ps
x-codeSamples:
- lang: PHP
source: |-
add_ons->get();
// Or, in 1 API request:
// $add_ons = Recurly_AddonList::get('gold');
foreach ($add_ons as $add_on) {
print "Add-on: $add_on\n";
}
} catch (Recurly_NotFoundError $e) {
print "Plan Not Found: $e";
}
- lang: Ruby
source: |-
plan = Recurly::Plan.find('gold')
plan.add_ons.find_each do |add_on|
puts "Add-on: #{add_on.inspect}"
end
- lang: Python
source: |-
#client version 2.1.6+
plan = Plan.get('gold')
for add_on in plan.add_ons():
print 'Add-on: %s' % add_on
#client version <= 2.1.5
plan = Plan.get('gold')
add_ons = plan.add_ons()
while add_ons:
for add_on in add_ons:
print 'Add-on: %s' % add_on
try:
add_ons = add_ons.next_page()
except PageError:
add_ons = ()
- lang: Dotnet
source: |-
using System.Linq;
var plan = Plans.Get("gold");
var addons = plan.AddOns;
while (addons.Any())
{
foreach (var addon in addons)
Console.WriteLine("Addon: " + addon);
addons = addons.Next;
}
post:
summary: Create Plan Add-On
description: >+
Add an add-on to a plan. Only one add-on can be created in a single
request.
tags:
- plan-add-ons
operationId: createPlanAddOn
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- add_on_code
- unit_amount_in_cents
- name
properties:
item_code:
type: string
default: ""
description:
Item code for an existing active item to be used as an add-on on
the plan. This will be unique identifier for add-on within
the plan.
add_on_code:
type: string
default: ""
description:
Add-on code. Max of 50 characters. If `item_code` present,
`add_on_code` must be absent. If `item_code` is not present,
`add_on_code` is required.
add_on_type:
type: string
default: ""
description:
Whether the add-on type is Fixed (fixed), or Usage-Based (usage).
If `item_code` is present, `add_on_type` must be absent.
default_quantity:
type: integer
default: "1"
description: Default quantity for the hosted pages.
unit_amount_in_cents:
type: array
items:
type: object
default: ""
description:
Array of unit amounts with their currency code. Max `10000000`.
Optional if `item_code` present and existing item has
default pricing. If `tiers` is present,
`unit_amount_in_cents` must be absent. Otherwise
`unit_amount_in_cents` is required.
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
name:
type: string
default: ""
description:
Add-on name. Max of 255 characters. If `item_code` present, `name`
must be absent. If `item_code` is not present, `name` is
required.
display_quantity_on_hosted_page:
type: boolean
default: "false"
description:
Default quantity for hosted pages. Must be true if `tier_type` !=
`flat`.
accounting_code:
type: string
default: ""
description:
Accounting code for invoice line items for the add-on, defaults to
the value of `add_on_code`. Max of 20 characters. If
`item_code` present, `accounting_code` must be absent.
revenue_schedule_type:
type: string
default: evenly
description:
Optional field for setting a revenue schedule type if `add_on_type`
= `fixed`. This will determine how revenue for the
associated Plan Add-On should be recognized. When creating a
Plan Add-On, available schedule types are `never`, `evenly`,
`at_range_start`, or `at_range_end`. If `item_code` present,
`revenue_schedule_type` must be absent.
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box
tax solution to determine taxation rules. You can pass in specific tax codes
using any of these tax integrations. For Recurly's In-the-Box tax offering
you can also choose to instead use simple values of `unknown`, `physical`, or
`digital` tax codes. If `item_code`/`item_id` is part of the request then
`tax_code` must be absent.
optional:
type: boolean
default: "true"
description:
Whether the add-on is optional for the customer to include in their
purchase on the hosted payment page. If false, the add-on
will be included when a subscription is created through the
Recurly UI. However, the add-on will not be included when a
subscription is created through the API. [Click
here](https://recurly.com/developers/api-v2/latest/#operation/createSubscriptionWithAddOns)
for how to create a subscription with add-ons using the API.
measured_unit_id:
type: string
default: ""
description:
The `id` of the measured unit on your site associated with the
add-on. If `item_code` present, `measured_unit_id` must be
absent.
usage_type:
type: string
default: ""
description:
If `add_on_type` = `usage`, you must set a `usage_type`, which can
be `price` or `percentage`. If `price`, the price is defined
in `unit_amount_in_cents` or by providing a `tier_type` and
a set of tiers. If `percentage`, the percentage is defined
in `usage_percentage`. If `item_code` is present,
`usage_type` must be absent.
usage_percentage:
$ref: "#/components/schemas/UsagePercentage"
usage_timeframe:
type: string
title: Usage Timeframe
description:
The time at which usage totals are reset for billing purposes.
It may be set to either `billing_period` or `subscription_term` and only applies when `tier_type` is `tiered`.
default: billing_period
tier_type:
type: string
default: flat
description:
The pricing model for the add-on. Defaults to `flat`. Other
options include `tiered`, `volume` or `stairstep`. Cannot be
changed once saved. For more information, [click
here](https://docs.recurly.com/docs/billing-models#section-quantity-based).
tiers:
$ref: "#/components/schemas/Tiers"
percentage_tiers:
$ref: "#/components/schemas/PlanPercentageTiers"
responses:
"201":
description: ""
content:
application/xml:
examples:
addOnFixed:
$ref: "#/components/examples/AddOnFixed"
addOnUsage:
$ref: "#/components/examples/AddOnUsage"
addOnItemBacked:
$ref: "#/components/examples/AddOnItemBacked"
addOnQuantityBased:
$ref: "#/components/examples/AddOnQuantityBased"
addOnItemBackedQuantityBased:
$ref: "#/components/examples/AddOnItemBackedQuantityBased"
addOnUseageQauntityBased:
$ref: "#/components/examples/AddOnUseageQauntityBased"
schema:
$ref: "#/components/schemas/AddOn"
x-codeSamples:
- lang: xml
source: >-
ipaddressesExtra IP Addresses200180evenlyvideo_streamingVideo Streamingusage12345678901234567890price5045t-shirt-12345150150plantertrueplantertiered500020003500planterusagetrue3065053711917834322plantertiered500020003500priceplanterusagepercentagetieredtrue3065053711917834322planterUSD10001020JPY2001525truegolden_sneakertiered500020003500
- lang: Ruby
source: |
# Created an add-on
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.create(
add_on_code: 'ipaddresses',
name: 'Extra IP Addresses',
unit_amount_in_cents: 2,
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
liability_gl_account_id: liability_gl_account.id,
revenue_gl_account_id: revenue_gl_account.id,
performance_obligation_id: pob.id
)
# Create a usage-based add-on
add_on = plan.add_ons.create!(
add_on_code: 'marketing_emails',
name: 'Marketing Emails',
unit_amount_in_cents: 50,
add_on_type: 'usage',
optional: false,
usage_type: 'price',
measured_unit_id: 18783,
)
# Create an item-backed add-on
add-on = plan.add_ons.create!(
item_code: item.item_code,
unit_amount_in_cents: 20,
# Recurly RevRec Standard/Advanced (RA-Managed)
# addon will use settings for the associated item if omitted,
# but can be explicitly set if desired.
liability_gl_account_id: liability_gl_account.id,
revenue_gl_account_id: revenue_gl_account.id,
performance_obligation_id: pob.id
)
# Create add-on with quantity-based pricing
add_on = plan.add_ons.create!(
add_on_code: "planter",
name: "Planter",
tier_type: "tiered",
tiers: [
Recurly::Tier.new({
unit_amount_in_cents: 5000,
ending_quantity: 2000
}),
Recurly::Tier.new({
unit_amount_in_cents: 3500
})
],
display_quantity_on_hosted_page: true
)
# Create usage-based add-on with quantity-based pricing
add_on = plan.add_ons.create!(
add_on_code: add_on_code,
name: add_on_code,
tier_type: "tiered",
display_quantity_on_hosted_page: true,
tiers: [
Recurly::Tier.new({
unit_amount_in_cents: 5000,
ending_quantity: 2000
}),
Recurly::Tier.new({
unit_amount_in_cents: 3500
})
],
add_on_type: "usage",
usage_type: "price",
measured_unit_id: measured_unit.id
)
# Create a tiered_usage_percentage add-on
add_on = plan.add_ons.create!(
add_on_code: add_on_code,
name: add_on_code,
tier_type: "tiered",
usage_timeframe: 'subscription_term',
display_quantity_on_hosted_page: true,
percentage_tiers: [
Recurly::CurrencyPercentageTier.new({
currency: 'USD',
tiers: [
Recurly::PercentageTier.new({
ending_amount_in_cents: 5000,
usage_percentage: 15.2
}),
Recurly::PercentageTier.new({
usage_percentage: 10
})
]
})
],
add_on_type: "usage",
usage_type: "percentage",
measured_unit_id: measured_unit.id
)
# Create an item-backed add-on with quantity-based pricing
add_on = plan.add_ons.create!(
item_code: item.item_code,
tier_type: "tiered",
tiers: [
Recurly::Tier.new({
unit_amount_in_cents: 5000,
ending_quantity: 2000
}),
Recurly::Tier.new({
unit_amount_in_cents: 3500
})
],
display_quantity_on_hosted_page: true
)
# Create percentage tiered add-on
addon = recurly.AddOn(
add_on_code = 'pothos',
name = 'Pothos Plant',
tier_type = "tiered",
add_on_type = "usage",
usage_type = "percentage",
measured_unit_id = str(measured_unit.id),
percentage_tiers = [
recurly.CurrencyPercentageTier(
currency = 'USD',
tiers = [
recurly.PercentageTier(
ending_amount_in_cents = 1000,
usage_percentage = '30'
),
recurly.PercentageTier(
usage_percentage = '40'
)
]
)
],
display_quantity_on_hosted_page = "true"
)
plan.create_add_on(addon)
- lang: Python
source: |
# Created an add-on
plan = Plan.get('gold')
addon = AddOn(
add_on_code='ipaddresses',
name='Extra IP Addresses',
unit_amount_in_cents=Money(USD=200,EUR=500),
# Recurly RevRec Standard/Advanced (RA-Managed)
# performance obligation IDs will be set to the default if omitted,
# but can be explicitly set if desired. general ledger account (gla)
# IDs will be `nil` if omitted (using business entity defaults at
# purchase time) but can also be explicitly set if desired.
liability_gl_account_id = liability_gl_account_id,
revenue_gl_account_id = revenue_gl_account_id,
performance_obligation_id = performance_obligation_id
)
plan.create_add_on(addon)
# Create an item-backed add-on
plan = Plan.get('gold')
addon = AddOn(
item_code = item.item_code,
unit_amount_in_cents = recurly.Money(USD=500),
# Create an item-backed add-on with RevRec settings
# Recurly RevRec Standard/Advanced (RA-Managed)
# addon will use settings for the associated item if omitted,
# but can be explicitly set if desired.
liability_gl_account_id = liability_gl_account_id,
revenue_gl_account_id = revenue_gl_account_id,
performance_obligation_id = performance_obligation_id
)
plan.create_add_on(addon)
# Create an add-on with quantity-based pricing
addon = recurly.AddOn(
add_on_code = 'planter',
name = 'Planter',
tier_type = "tiered",
tiers = [
recurly.Tier(
ending_quantity = 2000,
unit_amount_in_cents = recurly.Money(USD=5000)
),
recurly.Tier(
unit_amount_in_cents = recurly.Money(USD=3500)
)
],
display_quantity_on_hosted_page = "true",
)
plan.create_add_on(addon)
# Create usage-based add-on with quantity-based-pricing
addon = recurly.AddOn(
add_on_code = 'pothos',
name = 'Pothos Plant',
tier_type = "tiered",
tiers = [
recurly.Tier(
ending_quantity = 2000,
unit_amount_in_cents = recurly.Money(USD=1000)
),
recurly.Tier(
unit_amount_in_cents = recurly.Money(USD=800)
)
],
display_quantity_on_hosted_page = "true",
add_on_type = "usage",
usage_type = "price",
measured_unit_id = measured_unit.id
)
plan.create_add_on(addon)
# Create an item-backed add-on with quantity-based pricing
addon = recurly.AddOn(
item_code = item.item_code,
tier_type = "tiered",
tiers = [
recurly.Tier(
ending_quantity = 2000,
unit_amount_in_cents = recurly.Money(USD=5000)
),
recurly.Tier(
unit_amount_in_cents = recurly.Money(USD=3500)
)
],
display_quantity_on_hosted_page = "true",
)
plan.create_add_on(addon)
- lang: Dotnet
source: |-
// Create an add-on
var plan = Plans.Get("gold");
var addon = plan.NewAddOn("ipaddresses", "Extra IP Addresses"); // add-on code, name
addon.UnitAmountInCents.Add("USD", 200);
addon.UnitAmountInCents.Add("EUR", 180);
addon.DefaultQuantity = 1;
addon.DisplayQuantityOnHostedPage = true;
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
addon.LiabilityGlAccountId = liabilityGlaId;
addon.RevenueGlAccountId = revenueGlaId;
addon.PerformanceObligationId = performanceObligationId;
addon.Create();
// Create an item-backed add-on
var addon = plan.NewAddOn("item_code"); // item code
addon.UnitAmountInCents.Add("USD", 200);
// Recurly RevRec Standard/Advanced (RA-Managed)
// addon will use settings for the associated item if omitted,
// but can be explicitly set if desired.
addon.LiabilityGlAccountId = liabilityGlaId;
addon.RevenueGlAccountId = revenueGlaId;
addon.PerformanceObligationId = performanceObligationId;
addon.Create();
// Create an add-on with quantity-based pricing
var addon = plan.NewAddOn("planter", "Planter"); // add-on code, name
addon.TierType = "tiered";
addon.DisplayQuantityOnHostedPage = true;
var tier1 = new Tier();
tier1.UnitAmountInCents.Add("USD", 5000);
tier1.EndingQuantity = 2000;
addon.Tiers.Add(tier1);
var tier2 = new Tier();
tier2.UnitAmountInCents.Add("USD", 3500);
addon.Tiers.Add(tier2);
addon.Create();
// Create usage-based add-on with quantity-based pricing
var addon = plan.NewAddOn("ipaddresses", "Extra IP Addresses"); // add-on code, name
addon.TierType = "tiered";
addon.DisplayQuantityOnHostedPage = true;
addon.AddOnType = Recurly.AddOn.Type.Usage;
addon.UsageType = Recurly.Usage.Type.Price;
addon.MeasuredUnitId = measuredUnit.Id;
var tier = new Tier();
tier.UnitAmountInCents.Add("USD", 100);
tier.EndingQuantity = 60;
addon.Tiers.Add(tier);
var anotherTier = new Tier();
anotherTier.UnitAmountInCents.Add("USD", 50);
addon.Tiers.Add(anotherTier);
addon.Create();
# Create percentage tiered add-on
var addon = plan.NewAddOn("ipaddresses", "Extra IP Addresses");
addon.TierType = "tiered";
addon.AddOnType = Recurly.AddOn.Type.Usage;
addon.UsageType = Usage.Type.Percentage;
addon.DisplayQuantityOnHostedPage = true;
addon.MeasuredUnitId = measuredUnit.Id;
var currencyPercentageTier = new CurrencyPercentageTier();
currencyPercentageTier.Currency = "USD";
var percentageTier = new PercentageTier();
percentageTier.EndingAmountInCents = 1000;
percentageTier.UsagePercentage = "30";
currencyPercentageTier.PercentageTiers.Add(percentageTier);
var otherPercentageTier = new PercentageTier();
otherPercentageTier.UsagePercentage = "40";
currencyPercentageTier.PercentageTiers.Add(otherPercentageTier);
addon.CurrencyPercentageTiers.Add(currencyPercentageTier);
addon.Create();
// Create item-backed add-on with quantity-based pricing
var addon = plan.NewAddOn(item.ItemCode);
addon.TierType = "tiered";
addon.DisplayQuantityOnHostedPage = true;
var tier = new Tier();
tier.UnitAmountInCents.Add("USD", 100);
tier.EndingQuantity = 60;
addon.Tiers.Add(tier);
var anotherTier = new Tier();
anotherTier.UnitAmountInCents.Add("USD", 50);
addon.Tiers.Add(anotherTier);
addon.Create();
- lang: Java
source: |-
final AddOn ao = new AddOn();
ao.setAddOnCode("add_on_code");
ao.setName("name");
final RecurlyUnitCurrency price = new RecurlyUnitCurrency();
price.setUnitAmountUSD(10);
ao.setUnitAmountInCents(price);
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
ao.setLiabilityGlAccountId(liabilityGlaId);
ao.setRevenueGlAccountId(revenueGlaId);
ao.setPerformanceObligationId(pobId);
final AddOn addon = client.createPlanAddOn(planCode, ao);
- lang: PHP
source: |-
plan_code = 'gold';
$add_on->add_on_code = 'ipaddresses';
$add_on->name = 'Extra IP Addresses';
$add_on->unit_amount_in_cents->addCurrency('USD', 200);
$add_on->unit_amount_in_cents->addCurrency('EUR', 180);
// Recurly RevRec Standard/Advanced (RA-Managed)
// performance obligation IDs will be set to the default if omitted,
// but can be explicitly set if desired. general ledger account (gla)
// IDs will be `nil` if omitted (using business entity defaults at
// purchase time) but can also be explicitly set if desired.
$add_on->performance_obligation_id = $pob_id;
$add_on->revenue_gl_account_id = $revenue_gla_id;
$add_on->liability_gl_account_id = $liability_gla_id;
$add_on->create();
# Create an item-backed add-on
$add_on = new Recurly_Addon();
$add_on->plan_code = 'gold';
$add_on->item_code = $item->item_code;
$add_on->unit_amount_in_cents->addCurrency('USD', 400);
// Recurly RevRec Standard/Advanced (RA-Managed)
// addon will use settings for the associated item if omitted,
// but can be explicitly set if desired.
$add_on->performance_obligation_id = $pob_id;
$add_on->revenue_gl_account_id = $revenue_gla_id;
$add_on->liability_gl_account_id = $liability_gla_id;
$add_on->create();
# Create an add-on with quantity-based pricing
$add_on = new Recurly_Addon();
$add_on->plan_code = 'orchidsparkle';
$add_on->add_on_code = 'planter';
$add_on->name = 'Planter';
$add_on->tier_type = 'tiered';
$tier1 = new Recurly_Tier();
$tier1->unit_amount_in_cents->addCurrency('USD', 5000);
$tier1->ending_quantity = 2000;
$tier2 = new Recurly_Tier();
$tier2->unit_amount_in_cents->addCurrency('USD', 3500);
$add_on->tiers = array($tier1, $tier2);
$add_on->create();
# Create usage-based add-on with quantity-based pricing
$add_on = new Recurly_Addon();
$add_on->plan_code = $plan->plan_code;
$add_on->add_on_code = 'muppy';
$add_on->name = 'Muppy';
$add_on->tier_type = 'tiered';
$add_on->display_quantity_on_hosted_page = true;
$add_on->add_on_type = 'usage';
$add_on->usage_type = 'price';
$add_on->measured_unit_id = $unit->id;
$tier1 = new Recurly_Tier();
$tier1->unit_amount_in_cents->addCurrency('USD', 400);
$tier1->ending_quantity = 800;
$tier2 = new Recurly_Tier();
$tier2->unit_amount_in_cents->addCurrency('USD', 200);
$add_on->tiers = array($tier1, $tier2);
$add_on->create();
# Create an add-on with percentage tiers
$add_on = new Recurly_Addon();
$add_on->plan_code = $plan->plan_code;
$add_on->measured_unit_id = $measured_unit->id;
$add_on->add_on_code = 'add_on_code';
$add_on->tier_type = 'tiered';
$add_on->add_on_type = 'usage';
$add_on->usage_type = 'percentage';
$add_on->name = 'add_on_name';
$percentage_tier = new Recurly_PercentageTier();
$percentage_tier->currency = 'USD';
$tier = new Recurly_CurrencyPercentageTier();
$tier->ending_amount_in_cents = 100;
$tier->usage_percentage = '10.0';
$tier2 = new Recurly_CurrencyPercentageTier();
$tier2->ending_amount_in_cents = null;
$tier2->usage_percentage = '20.0';
$percentage_tier->tiers = array($tier, $tier2);
$add_on->percentage_tiers = array($percentage_tier);
$add_on->create();
# Create an item-backed add-on with quantity-based pricing
$add_on = new Recurly_Addon();
$add_on->plan_code = $plan->plan_code;
$add_on->item_code = $item->item_code;
$add_on->tier_type = 'tiered';
$add_on->display_quantity_on_hosted_page = true;
$tier1 = new Recurly_Tier();
$tier1->unit_amount_in_cents->addCurrency('USD', 400);
$tier1->ending_quantity = 800;
$tier2 = new Recurly_Tier();
$tier2->unit_amount_in_cents->addCurrency('USD', 200);
$add_on->tiers = array($tier1, $tier2);
$add_on->create();
"/plans/{plan_code}/add_ons/{add_on_code}":
parameters:
- $ref: "#/components/parameters/plan_code"
- in: path
name: add_on_code
schema:
type: string
required: true
description: The unique add-on code.
get:
summary: Lookup Plan Add-On
description: |+
Returns information about an add-on.
tags:
- plan-add-ons
operationId: lookupPlanAddOn
responses:
"200":
description: ""
content:
application/xml:
example: >-
ipaddressesExtra IP Addresses1false180200fixedtrueevenly2016-08-03T15:23:41Z2016-08-03T15:23:41Z
schema:
$ref: "#/components/schemas/AddOn"
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find AddOn with add_on_code = ipaddresses
x-codeSamples:
- lang: PHP
source: |-
+
Update the pricing information or description for an add-on. Existing
subscriptions with the add-on will not receive any pricing updates.
tags:
- plan-add-ons
operationId: updatePlanAddOn
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
name:
type: string
default: ""
description:
Add-on name. Max of 255 characters. If add-on has an associated
item, `name` is not updatable.
unit_amount_in_cents:
type: array
items:
type: object
default: ""
description:
Array of unit amounts with their currency code. Max 10000000. If
`tiers` is present, `unit_amount_in_cents` must be absent.
Otherwise `unit_amount_in_cents` is required.
default_quantity:
type: integer
default: ""
description: Default quantity for the hosted pages.
display_quantity_on_hosted_page:
type: string
default: ""
description:
If true, display a quantity field on the hosted pages for the
add-on. Must be true if `tier_type` != `flat`
accounting_code:
type: string
default: ""
description:
Accounting code for invoice line items for the add-on, defaults to
the value of `add_on_code`. Max of 20 characters. If add-on
has an associated item, `accounting_code` is not updatable.
revenue_schedule_type:
type: string
default: ""
description:
Optional field for setting a revenue schedule type if `add_on_type`
= `fixed`. This will determine how revenue for the
associated Plan Add-On should be recognized. When creating a
Plan Add-On, available schedule types are `never`, `evenly`,
`at_range_start`, or `at_range_end`. If add-on has an
associated item, `revenue_schedule_type` is not updatable.
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box
tax solution to determine taxation rules. You can pass in specific tax codes
using any of these tax integrations. For Recurly's In-the-Box tax offering
you can also choose to instead use simple values of `unknown`, `physical`, or
`digital` tax codes. If an `Item` is associated to the `AddOn` then
`tax_code` must be absent.
optional:
type: boolean
default: "true"
description:
Whether the add-on is optional for the customer to include in their
purchase on the hosted payment page. If false, the add-on
will be included when a subscription is created through the
Recurly UI. However, the add-on will not be included when a
subscription is created through the API. See
https://recurly.com/developers/api-v2/latest/#operation/createSubscriptionWithAddOns
for how to create a subscription with add-ons using the API.
measured_unit_id:
type: string
default: ""
description:
The id of the measured unit on your site associated with the
add-on. If add-on has an associated item, `measured_unit_id`
is not updatable.
usage_percentage:
$ref: "#/components/schemas/UsagePercentage"
tiers:
$ref: "#/components/schemas/Tiers"
percentage_tiers:
$ref: "#/components/schemas/PlanPercentageTiers"
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
responses:
"200":
description: ""
content:
application/xml:
examples:
addOnFixed:
$ref: "#/components/examples/AddOnFixed"
addOnQuantityBased:
$ref: "#/components/examples/AddOnQuantityBased"
addOnItemBacked:
$ref: "#/components/examples/AddOnItemBacked"
schema:
$ref: "#/components/schemas/AddOn"
x-codeSamples:
- lang: xml
source: |-
400360at_range_start20005000999999999644USD10001020JPY2001525
- lang: PHP
source: |-
unit_amount_in_cents['USD']->amount_in_cents = 1200; // $12.00.
// Recurly RevRec Standard/Advanced (RA-Managed)
$add_on->revenue_gl_account_id = $new_revenue_gla_id;
$add_on->liability_gl_account_id = $new_liability_gla_id;
$add_on->performance_obligation_id = $new_pob_id;
$add_on->update();
print "Addon: $add_on";
} catch (Recurly_ValidationError $e) {
print "Invalid Addon data: $e";
} catch (Recurly_NotFoundError $e) {
print "Plan or Addon Not Found: $e";
}
// Update an add-on with quantity-based pricing
$add_on = Recurly_Addon::get($plan->plan_code, $add_on->add_on_code);
$add_on->tiers[0]->ending_quantity = 123;
$add_on->update();
// Update an add-on with percentage tiers
$add_on = Recurly_Addon::get($plan->plan_code, $add_on->add_on_code);
$tier = new Recurly_CurrencyPercentageTier();
$tier->ending_amount_in_cents = 100;
$tier->usage_percentage = '10.0';
$tier2 = new Recurly_CurrencyPercentageTier();
$tier2->ending_amount_in_cents = null;
$tier2->usage_percentage = '20.0';
$add_on->percentage_tiers->tiers = array($tier, $tier2);
$add_on->update();
- lang: Ruby
source: |
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.find('ipaddresses')
add_on.update_attributes(
unit_amount_in_cents: 12_00,
# Recurly RevRec Standard/Advanced (RA-Managed)
liability_gl_account_id: new_liability_gl_account.id,
revenue_gl_account_id: new_revenue_gl_account.id,
performance_obligation_id: new_pob.id
)
# Update an add-on with quantity-based pricing
add_on.tiers[1].unit_amount_in_cents = 644
add_on.save!
# Update an add-on with quantity-based percentage pricing (tiered_usage_percentage add on)
add_on.percentage_tiers[0] = Recurly::CurrencyPercentageTier.new(
{
currency: 'USD',
tiers: [
Recurly::PercentageTier.new(
{
ending_amount_in_cents: 4999,
usage_percentage: 4.99
}
),
Recurly::PercentageTier.new(
{
usage_percentage: 10
}
)
]
}
)
add_on.save!
- lang: Python
source: |-
plan = Plan.get('gold')
add_on = plan.get_add_on('ipaddresses')
add_on.unit_amount_in_cents = Money(USD=200,EUR=500),
# Recurly RevRec Standard/Advanced (RA-Managed)
addon.liability_gl_account_id = liability_gl_account_id
addon.revenue_gl_account_id = revenue_gl_account_id
addon.performance_obligation_id = performance_obligation_id
add_on.save()
# Update an add-on with quantity-based pricing
tiers = add_on.tiers
add_on.tiers = []
for tier in tiers:
tempTier = recurly.Tier()
tempTier.unit_amount_in_cents = tier.unit_amount_in_cents
tempTier.ending_quantity = tier.ending_quantity
if tier == tiers[0]:
tempTier.ending_quantity = 1555
add_on.tiers.append(tempTier)
add_on.save()
# Update a percentage tiered add-on
new_percentage_tiers = [
recurly.CurrencyPercentageTier(
currency = 'USD',
tiers = [
recurly.PercentageTier(
ending_amount_in_cents = 1000,
usage_percentage = '35'
),
recurly.PercentageTier(
ending_amount_in_cents = 2000,
usage_percentage = '25'
),
recurly.PercentageTier(
usage_percentage = '20'
)
]
)
]
add_on.percentage_tiers = new_percentage_tiers
add_on.save()
- lang: Dotnet
source: |-
var plan = Plans.Get("gold");
var addon = plan.GetAddOn("ipaddresses");
addon.UnitAmountInCents["USD"] = 200;
addon.Update();
// Update an add-on with quantity-based pricing
addon.Tiers[0].EndingQuantity = 66;
addon.Tiers[1].UnitAmountInCents["USD"] = 66;
addon.Update();
# Update a percentage tiered add-on
var newPercentageTier = new PercentageTier();
newPercentageTier.UsagePercentage = "35";
newPercentageTier.EndingAmountInCents = 1000;
var newSecondPercentageTier = new PercentageTier();
newSecondPercentageTier.UsagePercentage = "25";
newSecondPercentageTier.EndingAmountInCents = 2000;
var newThirdPercentageTier = new PercentageTier();
newThirdPercentageTier.UsagePercentage = "20";
List newPercentageTiers = new List();
newPercentageTiers.Add(newPercentageTier);
newPercentageTiers.Add(newSecondPercentageTier);
newPercentageTiers.Add(newThirdPercentageTier);
addon.CurrencyPercentageTiers[0].PercentageTiers = newPercentageTiers;
// Recurly RevRec Standard/Advanced (RA-Managed)
addon.LiabilityGlAccountId = liabilityGlaId;
addon.RevenueGlAccountId = revenueGlaId;
addon.PerformanceObligationId = performanceObligationId;
addon.Update();
- lang: Java
source: |-
AddOn updateAddOn = new AddOn();
updateAddOn.setAddOnCode("add_on_code");
updateAddOn.setName("Tiered Add-On");
// Recurly RevRec Standard/Advanced (RA-Managed)
updateAddOn.setLiabilityGlAccountId(liabilityGlaId);
updateAddOn.setRevenueGlAccountId(revenueGlaId);
updateAddOn.setPerformanceObligationId(pobId);
final AddOn updatedAddOn = client.updateAddOn(planCode, addOnCode, updateAddOn);
System.out.println("Original AddOn: " + addOn);
System.out.println("AddOn updated: " + updatedAddOn);
delete:
summary: Delete Plan Add-On
description: |+
Remove an add-on from a plan.
tags:
- plan-add-ons
operationId: deletePlanAddOn
responses:
"204":
description: ""
content:
application/text:
example: "Status: 204 No Content"
x-codeSamples:
- lang: PHP
source: >-
delete();
print "Addon: $add_on";
} catch (Recurly_NotFoundError $e) {
print "Plan or Addon Not Found: $e";
}
- lang: Ruby
source: |-
plan = Recurly::Plan.find('gold')
add_on = plan.add_ons.find('ipaddresses')
add_on.destroy
- lang: Python
source: |-
plan = Plan.get('gold')
add_on = plan.get_add_on('ipaddresses')
add_on.delete()
- lang: Dotnet
source: |-
var plan = Plans.Get("gold");
var addon = plan.GetAddOn("ipaddresses");
addon.Delete();
"/accounts/{account_code}/subscriptions":
get:
summary: List Account's Subscriptions
description: |+
Returns a list of subscriptions for an account.
tags:
- subscriptions
operationId: listAccountsSubscriptions
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Unique account identifier.
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of subscriptions to return: `active`, `paused`,
`canceled`, `expired`, `future`, `in_trial`, `live`, or `past_due`.
A subscription may belong to more than one state. Please see the
previous section for a note on subscription states."
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
examples:
subscriptionsList:
summary: A List of Subscriptions
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:02:24Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trialsizelargegoldGold planevenly37bfee10b23c798312dedb4ead99c2e9expired4500EUR12016-08-03T16:00:51Z2016-08-03T16:02:16Z2016-08-03T16:02:16Z2016-08-03T16:02:16Z2016-08-03T16:00:51Z2016-09-03T16:00:51Z394usstCA0.08750netautomaticplan_free_trialsizelarge
rampSubscriptionsList:
$ref: "#/components/examples/RampSubscriptionListResponse"
x-codeSamples:
- lang: PHP
source: >-
If you need to purchase multiple subscriptions at once or
purchase a subscription along with additional charges or credits we
recommend using the [Preview Purchase](/docs/preview-purchase) endpoint
instead of this one. With it you can create an account, billing info,
charges, credits and subscriptions, then invoice and collect payment in
one step.
## Tax previews
The Preview Subscription endpoint will return tax if your site's
taxable customer address is provided in the call. This may be the
Billing Information address or the Account Information address depending
on your site settings. Tax previews are supported for both Recurly Basic
taxes and if you are using your own Avalara account.
tags:
- subscriptions
operationId: previewSubscription
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionCreatePreviewRequest"
examples:
withNewBillingInfo:
$ref: "#/components/examples/SubscriptionWithBillingInfoNewRequest"
withExistingBillingInfo:
$ref: "#/components/examples/SubscriptionWithBillingInfoExistingRequest"
withShippingInfo:
$ref: "#/components/examples/SubscriptionWithShippingInfoRequest"
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingOverrideRequest"
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionPreviewBasicResponse"
examples:
previewWithExistingAccount:
$ref: "#/components/examples/SubscriptionPreviewResponse"
"422":
$ref: "#/components/responses/SubscriptionErrors422"
x-codeSamples:
- lang: PHP
source: |-
plan_code = 'gold';
$subscription->currency = 'USD';
$account = new Recurly_Account();
$account->account_code = 'b6f5783';
$account->email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2017;
$billing_info->verification_value = 123;
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$subscription->shipping_amount_in_cents = 999;
$subscription->shipping_method_code = 'fast_fast_fast';
$account->billing_info = $billing_info;
$subscription->account = $account;
// if plan uses ramp pricing and you would like to override ramps:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 199),
new Recurly_SubscriptionRampInterval(4, 500)
);
$subscription->preview();
// $subscription has been updated with new attributes
print "$subscription->tax_in_cents\n";
print "$subscription->cost_in_cents\n";
print "Subscription: $subscription";
} catch (Recurly_ValidationError $e) {
print "Invalid Plan, Subscription, Account, or BillingInfo data: $e";
}
- lang: Ruby
source: |-
subscription = Recurly::Subscription.preview(
plan_code: 'gold',
currency: 'EUR',
account: {
account_code: '1',
email: 'verena@example.com',
first_name: 'Verena',
last_name: 'Example',
billing_info: {
number: '4111-1111-1111-1111',
month: 1,
year: 2014,
}
},
:shipping_address => {
:nickname => 'Work',
:first_name => 'Verena',
:last_name => 'Example',
:company => 'Recurly Inc',
:phone => '555-222-1212',
:email => 'verena@example.com',
:address1 => '123 Main St.',
:address2 => 'Suite 101',
:city => 'Grand Rapids',
:state => 'MI',
:zip => '49506',
:country => 'US'
}
:shipping_method_code => 'fast_fast_fast',
:shipping_amount_in_cents => 999,
# if plan uses ramp pricing and you would like to override ramps:
ramp_intervals: [
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: 1000
),
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: 2000
)
]
)
- lang: Python
source: |-
subscription = Subscription()
subscription.plan_code = 'gold'
subscription.currency = 'EUR'
account = recurly.Account(account_code='1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'
billing_info = BillingInfo()
billing_info.number = '4111-1111-1111-1111'
billing_info.month = 1
billing_info.year = 2014
account.billing_info = billing_info
subscription.account = account
subscription.shipping_method_code = 'fast_fast_fast'
subscription.shipping_amount_in_cents = 999
# if plan uses ramp pricing and you would like to override the ramps:
ramp_interval_1 = recurly.SubRampInterval(starting_billing_cycle=1, unit_amount_in_cents=6000)
ramp_interval_2 = recurly.SubRampInterval(starting_billing_cycle=3, unit_amount_in_cents=8000)
subscription.ramp_intervals = [ramp_interval_1, ramp_interval_2]
subscription.preview()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "USD"); // account, plan, currency
subscription.ShippingMethodCode = "fast_fast_fast";
subscription.ShippingAmountInCents = 999;
// if plan uses ramp pricing and you would like to override the ramps:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
subscription.Preview();
"/subscriptions":
get:
summary: List Subscriptions
description: "Returns a list of all the subscriptions.
**Subscription Query States**
| state | description |
| --- | --- |
| active | Subscriptions that are valid for the current time.
This includes subscriptions in a trial period |
| canceled | Subscriptions that are valid for the current time
but will not renew because a cancelation was requested |
| paused | Subscriptions that are currently paused |
| expired | Subscriptions that have expired and are no longer
valid |
| future | Subscriptions that will start in the future, they are
not active yet |
| in_trial | Subscriptions that are active or canceled and are
in a trial period |
| live | All subscriptions that are not expired |
| past_due | Subscriptions that are active or canceled and have
a past-due invoice |
Please note: a queried state and the base state of a returned
subscription may differ. For example, querying for past_due
subscriptions will not result in a list of subscriptions with a
'past_due' state (they will either be 'active' or 'canceled'). Only base
states ('pending', 'active', 'canceled', 'expired', 'future') will be
present in the returned subscription records.
\ "
tags:
- subscriptions
operationId: listSubscriptions
parameters:
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of subscriptions to return: `active`, `paused`,
`canceled`, `expired`, `future`, `in_trial`, `live`, or `past_due`.
A subscription may belong to more than one state."
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionsListResponse"
examples:
subscriptionsList:
$ref: "#/components/examples/SubscriptionListResponse"
rampSubscriptionsList:
$ref: "#/components/examples/RampSubscriptionListResponse"
x-codeSamples:
- lang: PHP
source: |-
= 2.1.6
for subscription in Subscription.all():
print 'Subscription: %s' % subscription
#client version <= 2.1.5
subscriptions = Subscription.all()
while subscriptions:
for subscription in subscriptions:
print 'Subscription: %s' % subscription
try:
subscriptions = subscriptions.next_page()
except PageError:
subscriptions = ()
- lang: Dotnet
source: |-
using System.Linq;
var subscriptions = Subscriptions.List();
while (subscriptions.Any())
{
foreach (var subscription in subscriptions)
Console.WriteLine("Subscription: " + subscription);
subscriptions = subscriptions.Next;
}
post:
summary: Create Subscription
description: |-
### Consider using Purchases
If you need to purchase multiple subscriptions at once or purchase a subscription along with additional charges or credits we recommend using the [Create Purchase](/docs/create-purchase) endpoint instead of this one. With it you can create an account, billing info, charges, credits and subscriptions, then invoice and collect payment in one step.
#### SUBSCRIPTION STARTS DATE
If you would like the subscription to start on a specified date, please set the `trial_ends_at` parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system.
#### CREATING AN ACCOUNT SIMULTANEOUSLY
To avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription.
#### USING STORED BILLING INFO
You may create a subscription without specifying billing information if an account already has stored billing information.
#### REDEEMING A COUPON
Redeem coupon codes within the create subscription action as a convenience or as a way to make sure the coupon is only redeemed if the subscription transaction is successful.
If you are redeeming one coupon, pass in coupon_code:
```xml
special1
```
If you want to redeem multiple coupons, use the following format:
```xml
special1special2
```
NOTE: You must have Multiple Coupons Per Account enabled in Coupon Settings in order to redeem multiple coupons in the create subscription action.
The coupon must have eligible charges that include the plan of the subscription you are creating. If the coupon has a redemption_resource of "subscription", it will automatically be tied to the subscription upon successful redemption.
If you are redeeming a free trial coupon and also setting a trial_ends_at in the request, the subscriptions trial will follow the trial_ends_at, not the coupon rules.
#### REDEEMING A GIFT CARD
Redeem a gift card redemption code within the create subscription action as a convenience or as a way to make sure the gift card is only redeemed if the subscription transaction is successful. Only one gift card redemption code can be redeemed in the request
Example XML Request:
```xml
JHD776JENN99E6DD
```
Note that the subscription response will not include information about the gift card, but will add two new parameters, `started_with_gift` and `converted_at`.
tags:
- subscriptions
operationId: createSubscription
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionCreatePreviewRequest"
examples:
withNewBillingInfo:
$ref: "#/components/examples/SubscriptionWithBillingInfoNewRequest"
withExistingBillingInfo:
$ref: "#/components/examples/SubscriptionWithBillingInfoExistingRequest"
withShippingInfo:
$ref: "#/components/examples/SubscriptionPreviewRequest"
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingOverrideRequest"
responses:
"201":
description: "CREATED"
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionFixedPricingCreateResponse"
examples:
createResponse:
$ref: "#/components/examples/SubscriptionFixedPricingCreateResponse"
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingResponse"
"422":
$ref: "#/components/responses/SubscriptionErrors422"
x-codeSamples:
- lang: PHP
source: |-
plan_code = 'gold';
$subscription->currency = 'EUR';
$account = new Recurly_Account();
$account->account_code = 'b6f5783';
$account->email = 'verena@example.com';
$account->first_name = 'Verena';
$account->last_name = 'Example';
# Create subscription with new billing info
$billing_info = new Recurly_BillingInfo();
$billing_info->number = '4111-1111-1111-1111';
$billing_info->month = 12;
$billing_info->year = 2019;
$billing_info->verification_value = '123';
$billing_info->address1 = '400 Alabama St';
$billing_info->city = 'San Francisco';
$billing_info->state = 'CA';
$billing_info->country = 'US';
$billing_info->zip = '94110';
$account->billing_info = $billing_info;
# Or create subscription with existing billing info
$subscription->billing_info_uuid = "billingInfoUuid";
$subscription->account = $account;
$subscription->shipping_amount_in_cents = 999;
$subscription->shipping_method_code = 'fast_fast_fast';
// if plan uses ramp pricing and you would like to override ramps:
$subscription->ramp_intervals = array(
new Recurly_SubscriptionRampInterval(1, 199),
new Recurly_SubscriptionRampInterval(4, 500)
);
$subscription->create();
print "Subscription: $subscription";
} catch (Recurly_ValidationError $e) {
print "Invalid Plan, Subscription, Account, or BillingInfo data: $e";
}
- lang: Ruby
source: |-
# Create subscription with new billing info
subscription = Recurly::Subscription.create(
:plan_code => 'gold',
:currency => 'EUR',
:customer_notes => 'Thank you for your business!',
:account => {
:account_code => '1',
:email => 'verena@example.com',
:first_name => 'Verena',
:last_name => 'Example',
:billing_info => {
:number => '4111-1111-1111-1111',
:month => 1,
:year => 2014,
}
},
:shipping_address => {
:nickname => 'Work',
:first_name => 'Verena',
:last_name => 'Example',
:company => 'Recurly Inc',
:phone => '555-222-1212',
:email => 'verena@example.com',
:address1 => '123 Main St.',
:address2 => 'Suite 101',
:city => 'San Francisco',
:state => 'CA',
:zip => '94105',
:country => 'US'
}
:shipping_method_code => 'fast_fast_fast',
:shipping_amount_in_cents => 999,
# if plan uses ramp pricing and you would like to override ramps:
ramp_intervals: [
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: 1000
),
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: 2000
)
]
)
# Create subscription with existing billing info
subscription = Recurly::Subscription.create!(
plan_code: 'gold',
currency: 'USD',
unit_amount_in_cents: 1200,
billing_info_uuid: 'billing-info-uuid',
account: {
account_code: '1'
}
)
- lang: Python
source: |-
# Create subscription with new billing info
subscription = Subscription()
subscription.plan_code = 'gold'
subscription.currency = 'EUR'
account = Account.get('1')
account.email = 'verena@example.com'
account.first_name = 'Verena'
account.last_name = 'Example'
billing_info = BillingInfo()
billing_info.number = '4111-1111-1111-1111'
billing_info.month = 12
billing_info.year = 2019
account.billing_info = billing_info
subscription.account = account
subscription.shipping_method_code = 'fast_fast_fast'
subscription.shipping_amount_in_cents = 999
# if plan uses ramp pricing and you would like to override the ramps:
ramp_interval_1 = recurly.SubRampInterval(starting_billing_cycle=1, unit_amount_in_cents=6000)
ramp_interval_2 = recurly.SubRampInterval(starting_billing_cycle=3, unit_amount_in_cents=8000)
subscription.ramp_intervals = [ramp_interval_1, ramp_interval_2]
subscription.save()
# Create subscription new existing billing info
subscription = recurly.Subscription()
subscription.plan_code = 'gold'
subscription.account = Account.get('1')
...
subscription.billing_info_uuid = "billingInfoUuid"
subscription.save()
- lang: Dotnet
source: |-
// Create subscription with new billing info
var account = new Account("1")
{
Email = "verena@example.com",
FirstName = "Verena",
LastName = "Example",
BillingInfo = new BillingInfo(new Account("1"))
{
FirstName = "Verana",
LastName = "Example",
CreditCardNumber = "4111-1111-1111-1111",
VerificationValue = "123",
ExpirationMonth = 12,
ExpirationYear = 2019
}
};
var plan = Plans.Get("gold");
var subscription = new Subscription(account, plan, "EUR"); // account, plan, currency
subscription.ShippingMethodCode = "fast_fast_fast";
subscription.ShippingAmountInCents = 999;
// if plan uses ramp pricing and you would like to override the ramps:
subscription.RampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
subscription.Create();
// Create subscription with existing billing info
var sub = new Subscription(account, plan, "USD");
sub.BillingInfoUuid = "billingInfoUuid";
sub.Create();
"/subscriptions/{uuid}":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
get:
summary: Lookup Subscription
description: >-
Lookup a subscription's details.
### Pending Subscription Changes
When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.
### Paused Subscriptions and `current_term_ends_at` timestamp
While a subscription is paused, the `current_term_ends_at` timestamp of the subscription will not be updated to account for the time while the subscription is paused (e.g the timestamp does not get pushed out by the number of paused periods). This is due to the fact that the subscription could be resumed earlier or the number of pause periods can frequently be updated. Any of the former events could potentially change the timestamp. Once a subscription is returned to active, the `current_term_renewal_date` will be updated.
To calculate the new renewal date while a subscription is paused, you will want to take original renewal date add the length of the pause period.
| Subscription Parameters | Description |
| --- | --- |
| plan | Nested plan_code and plan name |
| uuid | Unique subscription ID |
| state | `active`, `canceled`, `future`, `expired`, `paused` |
| unit_amount_in_cents | Unit amount of the subscription |
| quantity | Number of units |
| currency | 3-letter ISO currency for the subscription |
| activated_at | Date the subscription was activated |
| canceled_at | Date the subscription was marked canceled |
| expires_at | Date the subscription will end (if state is `canceled`) or ended (if state is `expired`) |
| auto_renew | True if subscription term set to auto renew at end of term |
| current_period_started_at | Date the current billing period started |
| current_period_ends_at | Date the current billing period will end |
| current_term_started_at | Date and time that the current term started at. |
| current_term_ends_at | Date and time that the current term will end (or the date and time the term will renew if auto_renew is true) |
| total_billing_cycles | Total number of billing periods in the current term. |
| remaining_billing_cycles | Remaining number of billing periods in the current subscription term. Always set to 0 for subscriptions with a single billing period term. |
| renewal_billing_cycles | Total number of billing periods in the subscription's next term, if auto_renew is true |
| trial_started_at | Date the trial was started, if applicable |
| trial_ends_at | Date the trial ended, if applicable |
| tax_in_cents | Amount of tax or VAT within the transaction, in cents. |
| tax_type | Tax type as "vat" for VAT or "usst" for US Sales Tax. |
| tax_region | Region where taxes are applied. |
| tax_rate | Tax rate that will be applied to this subscription. |
| po_number | PO number reference. |
| net_terms | Invoice net terms in days. |
| collection_method | Invoice collection as "automatic" or "manual". |
| subscription_add_ons | Nested list of add-ons on the subscription, if applicable |
| pending_subscription | Nested information about a pending subscription change at renewal |
| terms_and_conditions | Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals. |
| customer_notes | Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. |
| bank_account_authorized_at | Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist. |
| plan | Nested information about the new plan |
| unit_amount_in_cents | New subscription's unit amount in cents |
| quantity | New subscription quantity |
| subscription_add_ons | Nested list of add-ons |
| started_with_gift | True if the subscription started from a gift card. |
| converted_at | The timestamp representing when the subscription was converted from a gift card. |
tags:
- subscriptions
operationId: lookupSubscription
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionFixedPricingCreateResponse"
examples:
common:
$ref: "#/components/examples/SubscriptionFixedPricingCreateResponse"
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingResponse"
x-codeSamples:
- lang: PHP
source: >-
If you need to update a canceled subscription, you need to first reactivate the subscription and then do the update call. You can look for the canceled subscription state to know if you need to do the reactivate call first.
While changing a canceled subscription may reactivate the subscription in some cases, there are scenarios where it will not reactivate the subscription, so we do not recommend allowing changes on a canceled subscription.
If you do submit an at renewal change to a canceled subscription and do not reactivate the subscription, it will expire at the end of the subscription term.
### TIMEFRAME
The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur immediately, the next time the subscription is billed, or when the subscription renews. Generally, if you're performing an upgrade, you will want the change to occur immediately (`now`) or the next time the subscription is billed (`bill_date`). If you're performing a downgrade, you'll want the change to happen when the subscription renews (`term_end`) or the next time the subscription is billed (`bill_date`) so the customer gets what they paid for in their current billing cycle or term. The `renewal` timeframe option is accepted as an alias for `term_end`.
The timeframe control only applies to changes to the subscription's products. All non-product changes are always applied immediately. These changes have the option of applying at term end or bill date: `plan_code`, `quantity`, `unit_amount_in_cents`, `subscription_add_ons`.
#### Updating Refunded Subscriptions
Without the Credit Invoices feature enabled, Recurly does not reconcile invoice payments with subscription requests. If a subscription has a refund in the current billing cycle, updates with a timeframe of `now` will always credit the customer as if the refund never existed. Updates with a timeframe of `term_end` will not have this problem. Learn more.
### ADD-ONS
If you include the `subscription_add_ons` array in your request, the subscription's original add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change. If you do not include the `subscription_add_ons` array, your current add-ons will remain in the subscription.
### COUPONS
You can redeem a coupon in a subscription update if the update has a timeframe of `now` and you change something else about the subscription that triggers an invoice, like the plan, quantity, or price.
The coupon must include the subscription's plan as an eligible charge.
You can redeem multiple coupons with this format:
```xml
savemoreholidayspecial
```
tags:
- subscriptions
operationId: updateSubscription
requestBody:
required: true
content:
application/xml:
schema: # this includes field requirements (should eventually fix)
$ref: "#/components/schemas/SubscriptionCreatePreviewRequest"
examples:
fixedPricing:
$ref: "#/components/examples/SubscriptionUpdateFixedPricingRequest"
rampPricing:
$ref: "#/components/examples/SubscriptionUpdateRampPricingRequest"
responses:
"200":
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionFixedPricingCreateResponse"
examples:
fixedPricing:
$ref: "#/components/examples/SubscriptionUpdateFixedPricingResponse"
rampPricing:
$ref: "#/components/examples/SubscriptionUpdateRampPricingResponse"
x-codeSamples:
- lang: PHP
source: |-
plan_code = 'silver';
$subscription->quantity = 2;
$subscription->billing_info_uuid = 'billingInfoUuid';
// if wanting to update any current/future ramp intervals
// for ramp-priced subscriptions
$newRamp1Price = new Recurly_SubscriptionRampInterval(1, 150);
$subscription->ramp_intervals[1]->starting_billing_cycle = 4;
array_splice($subscription->ramp_intervals, 0, 1, [$newRamp1Price]);
$subscription->updateImmediately(); // Update immediately.
// or $subscription->updateAtRenewal(); // Update when the subscription renews.
// or $subscription->updateAtNextBillDate(); // Update next time the subscription is billed
print "Subscription: $subscription";
} catch (Recurly_ValidationError $e) {
print "Invalid Subscription data: $e";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.update_attributes!(
plan_code: 'silver',
quantity: 2,
billing_info_uuid: 'billingInfoUuid',
# if wanting to update any current/future ramp intervals
# for ramp-priced subscriptions
ramp_intervals: [
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: 1000
),
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: 2000
)
],
timeframe: 'now' # Update immediately.
timeframe: 'term_end' # Update when the subscription renews.
timeframe: 'bill_date' # Update next time the subscription is billed
)
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.plan_code = 'silver'
subscription.quantity = 2
subscription.billing_info_uuid = 'billingInfoUuid'
subscription.timeframe = 'now' # Update immediately.
# subscription.timeframe = 'term_end' # Update when the subscription renews.
# subscription.timeframe = 'bill_date' # Update next time the subscription is billed.
# if wanting to update any current/future ramp intervals
# for ramp-priced subscriptions
ramp_interval_1 = recurly.SubRampInterval(starting_billing_cycle=1, unit_amount_in_cents=6000)
ramp_interval_2 = recurly.SubRampInterval(starting_billing_cycle=3, unit_amount_in_cents=8000)
subscription.ramp_intervals = [ramp_interval_1, ramp_interval_2]
subscription.save()
- lang: Dotnet
source: |-
var subscriptionUuid = "4adc47cb1be5576fd9a6f544ceb699c8";
// if wanting to update any current/future ramp intervals
// for ramp-priced subscriptions
var newRampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
var change = new SubscriptionChange
{
RampIntervals = newRampIntervals,
TimeFrame = SubscriptionChange.ChangeTimeframe.Now,
// or TimeFrame = SubscriptionChange.ChangeTimeframe.Renewal
// or TimeFrame = SubscriptionChange.ChangeTimeframe.BillDate
PlanCode = "silver",
Quantity = 2,
BillingInfoUuid = "billingInfoUuid"
};
// perform the update operation
Subscription.ChangeSubscription(subscriptionUuid, change);
"/subscriptions/{uuid}/notes":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Update Subscription Notes
description:
"Update a subscription's invoice notes before the next renewal.
Updating notes will not trigger the renewal.
Please note that this example is provided for illustrative
purposes and is not a separate endpoint from 'Update Subscription'
\ "
tags:
- subscriptions
operationId: updateSubscriptionNotes
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
terms_and_conditions:
type: string
default: ""
description:
Optional notes field. This will default to the Terms and Conditions
text specified on the Invoice Settings page in your Recurly
admin, unless custom notes were created with the original
subscription. Specify custom notes with this tag to add or
override Terms and Conditions. Custom notes will stay with a
subscription on all renewals, unless updated before renewal.
Will always change immediately, even if `timeframe` =
`term_end`.
customer_notes:
type: string
default: ""
description:
Optional notes field. This will default to the Customer Notes text
specified on the Invoice Settings page in your Recurly
admin, unless custom notes were created with the original
subscription. Specify custom notes with this tag to add or
override Customer Notes. Custom notes will stay with a
subscription on all renewals. Will always change
immediately, even if `timeframe` = `term_end`.
vat_reverse_charge_notes:
type: string
default: ""
description:
VAT Reverse Charge Notes only appear if you have EU VAT enabled or
are using your own Avalara AvaTax account and the customer
is in the EU, has a VAT number, and is in a different
country than your own. This will default to the VAT Reverse
Charge Notes text specified on the Tax Settings page in your
Recurly admin, unless custom notes were created with the
original subscription. Specify custom notes with this tag to
add or override VAT Reverse Charge Notes. Custom notes will
stay with a subscription on all renewals. Will always change
immediately, even if `timeframe` = `term_end`.
custom_fields:
type: array
items:
type: object
default: ""
description: Optional custom fields for the subscription.
gateway_code:
type: string
default: ""
description:
An alphanumeric code shown per gateway on your site's payment
gateways page. Set this code to ensure that a given
subscription targets a given gateway.
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:11:19Z2016-08-03T16:02:24Z2016-09-03T16:02:24ZPayment can be sent to Acme Cloud, Inc.Thanks for your business!394usstCA0.08750netautomaticplan_free_trialfoodtaco
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingNotesResponse"
x-codeSamples:
- lang: xml
source: >-
Payment can be sent to Acme Cloud, Inc.Thanks for your business!No VAT was applied on this invoice. Please reference this legislation.jg7fin35hde6foodtaco
- lang: PHP
source: >-
custom_fields["food"];
$cf->value = "taco";
$subscription->updateNotes(array(
"customer_notes" => "New Customer Notes",
"terms_and_conditions" => "New Terms",
"vat_reverse_charge_notes" => "New VAT Notes"
));
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
// note: calling 'updateAtRenewal()' will throw the following error: "The provided XML was invalid. Details: Unacceptable tag ." Please use 'updateNotes()' instead.
// example of incorrect method of updating notes:
// $sub->customer_notes='New Customer Notes';
// $sub->updateAtRenewal();
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
# you can optionally add or edit custom fields here
subscription.custom_fields << Recurly::CustomField.new(name: 'food', value: 'taco')
# you can set existing value to nil to clear
# subscription.custom_fields.first.value = nil
subscription.update_notes(
customer_notes: 'New Customer Notes',
terms_and_conditions: 'New Terms',
vat_reverse_charge_notes: 'New VAT Notes'
)
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
# you can optionall add or edit custom fields here too
subscription.custom_fields[0].value = 'taco'
subscription.update_notes(customer_notes='New Customer Notes',
terms_and_conditions='New Terms',
vat_reverse_charge_notes='New VAT Notes')
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("37bfef7a8e44cfc3817b7a43eba8a6e6");
subscription.CustomFields = new List(new CustomField[] { new CustomField("food", "taco") });
var dict = new Dictionary();
dict.Add("CustomerNotes", "Thanks for your business!");
dict.Add("TermsAndConditions", "Payment can be sent to Acme Cloud, Inc.");
subscription.UpdateNotes(dict);
"/subscriptions/{uuid}/cancel":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Cancel Subscription
description:
"Cancel a subscription so it remains active and then expires at the
end of the current bill cycle.
Canceling a subscription turns off the subscription's
auto-renewal. The subscription will continue through the current,
invoiced term. When the subscription is up for renewal, the account will
transition to a free account and the subscription will no longer be
active.
When a subscription is canceled, Recurly will send a cancelation
webhook. Recurly will send an additional subscription expired webhook
once the subscription is no longer active.
Please note: If a subscription that is set to start in the
future is canceled, the subscription will be deleted from the account
and will not show up in the account's subscription list.
\ "
tags:
- subscriptions
operationId: cancelSubscription
parameters:
- in: query
name: timeframe
schema:
type: string
default: ""
description:
"`bill_date` to expire when the subscription next bills, `term_end`
to expire at the end of the subscription term."
- in: path
name: uuid
schema:
type: string
required: true
description: Uuid.
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6canceled4500EUR12016-08-03T16:02:24Z2016-08-03T16:10:54Z2016-09-03T16:02:24Z2016-08-03T16:10:54Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trialsizelarge
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingCancelResponse"
x-codeSamples:
- lang: PHP
source: >-
cancel();
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
} catch (Recurly_Error $e) {
print "Subscription already canceled: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.cancel
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.cancel()
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Cancel();
"/subscriptions/{uuid}/reactivate":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Reactivate Canceled Subscription
description: >-
Reactivate a canceled subscription so it renews at the end of the
current bill cycle.
When a subscription is canceled, it will not renew. It is considered active until the end of the current billing period. Then, the subscription will end. To renew the subscription without modifying it, simply send a reactivation request to this end point.
tags:
- subscriptions
operationId: reactivateCanceledSubscription
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:11:05Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trialsizelarge
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingResponse"
x-codeSamples:
- lang: PHP
source: >-
reactivate();
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
} catch (Recurly_Error $e) {
print "Subscription already reactivated: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.reactivate
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.reactivate()
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Reactivate();
"/subscriptions/{uuid}/terminate":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Terminate Subscription
description: >-
| Refund Type | Description |
| --- | --- |
| partial | Prorates a refund based on the amount of time remaining in the current bill cycle. |
| full | Performs a full refund of the last charge for the current subscription term. |
| none | Terminates the subscription without a refund. |
tags:
- subscriptions
operationId: terminateSubscription
parameters:
- in: query
name: refund
schema:
enum:
- partial
- full
- none
default: none
description:
"`partial`, `full`, or `none` refund processed on the subscription
charges."
- in: query
name: charge
schema:
type: boolean
default: true
description:
"Allowed if Usage-Based Billing Beta enabled on your site: If
`true`, current billing cycle unbilled usage is billed on the final
invoice. If `false`, Recurly will create a negative usage record for
current billing cycle usage that will zero out the final invoice
line items."
- in: path
name: uuid
schema:
type: string
required: true
description: Uuid.
responses:
"200":
description: ""
content:
application/xml:
example: >-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6expired4500EUR12016-08-03T16:02:24Z2016-08-03T16:12:14Z2016-08-03T16:12:14Z2016-08-03T16:12:14Z2016-08-03T16:02:24Z2016-09-01T00:00:00ZPayment can be sent to Acme Cloud, Inc.Thanks for your business!394usstCA0.08750netautomaticplan_free_trialsizelarge
x-codeSamples:
- lang: PHP
source: >-
terminateWithoutRefund();
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
} catch (Recurly_Error $e) {
print "Subscription already terminated: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.terminate :partial
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.terminate(refund='partial')
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Terminate(Subscription.RefundType.Full);
//subscription.Terminate(Subscription.RefundType.Partial);
//subscription.Terminate(Subscription.RefundType.None);
"/subscriptions/{uuid}/postpone":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Postpone Subscription or Extend Trial
description: >-
For an active subscription, this will change the next bill date. For a
subscription in a trial period, modifying the next bill date will change
when the trial expires.
Use this endpoint to:
* Force a subscription to renew early
* Keep a subscription from renewing until a later date
* Shorten a trial period
* Lengthen a trial period
tags:
- subscriptions
operationId: postponeSubscriptionOrExtendTrial
parameters:
- in: query
name: next_bill_date
schema:
type: string
format: date-time
required: true
description:
Use this field to adjust the next bill date of a subscription.
Cannot postpone subscriptions while they are in a paused state.
- in: query
name: bulk
schema:
type: boolean
default: false
description:
Optional field to be used only when needing to bypass the 60 second
limit on creating subscriptions. Should only be used when creating
subscriptions in bulk from the API. Set to `true` or `false`.
Defaults to `false`.
- in: query
name: next_renewal_date
schema:
type: string
format: date-time
default: ""
description:
"DEPRECATED: Please use `next_bill_date`. A future date when the
subscription should be billed."
- in: path
name: uuid
schema:
type: string
required: true
description: Uuid.
responses:
"200":
description: ""
content:
application/xml:
example: >-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:12:02Z2016-08-03T16:02:24Z2019-12-31T00:00:00ZPayment can be sent to Acme Cloud, Inc.Thanks for your business!394usstCA0.08750netautomaticplan_free_trialsizelarge
x-codeSamples:
- lang: PHP
source: >-
postpone(date('c', strtotime('2019-12-31Z')));
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.postpone Time.utc(2019, 12, 31), false
- lang: Python
source: >-
sub = Subscription.get('44f83d7cba354d5b84812419f923ea96')
sub.postpone(next_bill_date=datetime.datetime(2019, 12, 31), bulk=False)
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("44f83d7cba354d5b84812419f923ea96");
subscription.Postpone(new DateTime(2019, 12, 31), false);
"/subscriptions/{uuid}/preview":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
post:
summary: Preview Subscription Change
description:
"Returns a preview for a subscription change applied to an account
without committing a subscription change or posting an invoice.
###### Free Trials
Subscriptions in trial will not generate an invoice for an
immediate change. Due to this, the subscription change preview for a
subscription in trial will not return an invoice object.
\ "
tags:
- subscriptions
operationId: previewSubscriptionChange
requestBody:
required: true
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionCreatePreviewRequest"
examples:
fixedPricing:
$ref: "#/components/examples/SubscriptionUpdateFixedPricingRequest"
rampPricing:
$ref: "#/components/examples/SubscriptionUpdateRampPricingRequest"
responses:
"201":
description: "Created"
content:
application/xml:
schema:
$ref: "#/components/schemas/SubscriptionFixedPricingCreateResponse"
examples:
fixedPricing:
$ref: "#/components/examples/SubscriptionUpdatePreviewFixedPricingResponse"
rampPricing:
$ref: "#/components/examples/SubscriptionUpdatePreviewRampPricingResponse"
quantityBasedPercentage:
$ref: "#/components/examples/SubscriptionUpdatePreviewQuantityBasedPercentage"
x-codeSamples:
- lang: PHP
source: |-
unit_amount_in_cents = 1000;
// if wanting to update any current/future ramp intervals
// for ramp-priced subscriptions
$newRamp1Price = new Recurly_SubscriptionRampInterval(1, 150);
$subscription->ramp_intervals[1]->starting_billing_cycle = 4;
array_splice($subscription->ramp_intervals, 0, 1, [$newRamp1Price]);
$subscription->preview();
$charge_invoice = $subscription->invoice_collection->charge_invoice;
// to view entire adjustment
foreach ($charge_invoice->line_items as $adjustment) {
print("Adjustment: $adjustment\n");
}
// to preview next invoice amount
print "Invoice Total: $charge_invoice->total_in_cents\n";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
subscription.unit_amount_in_cents = 1000
# if wanting to update any current/future ramp intervals
# for ramp-priced subscriptions
subscription.ramp_intervals = [
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 1,
unit_amount_in_cents: 1000
),
Recurly::SubscriptionRampInterval.new(
starting_billing_cycle: 2,
unit_amount_in_cents: 2000
)
]
subscription.shipping_address = {
:nickname => 'Work',
:first_name => 'Verena',
:last_name => 'Example',
:company => 'Recurly Inc',
:phone => '555-222-1212',
:email => 'verena@example.com',
:address1 => '123 Main St.',
:address2 => 'Suite 101',
:city => 'Grand Rapids',
:state => 'MI',
:zip => '49506',
:country => 'US'
}
subscription.preview
subscription.invoice.line_items.each do |line_item|
puts line_item
end
- lang: Python
source: |-
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
subscription.unit_amount_in_cents = 1000
# if wanting to update any current/future ramp intervals
# for ramp-priced subscriptions
ramp_interval_1 = recurly.SubRampInterval(starting_billing_cycle=1, unit_amount_in_cents=6000)
ramp_interval_2 = recurly.SubRampInterval(starting_billing_cycle=3, unit_amount_in_cents=8000)
subscription.ramp_intervals = [ramp_interval_1, ramp_interval_2]
subscription.preview()
for line_item in sub.invoice.line_items:
print line_item
- lang: Dotnet
source: |-
var subUuid = "43ae00fadf77887688fe9c4041b7af19";
// if wanting to update any current/future ramp intervals
// for ramp-priced subscriptions
var newRampIntervals = new List
{
new SubscriptionRampInterval()
{
StartingBillingCycle = 1,
UnitAmountInCents = 500
},
new SubscriptionRampInterval()
{
StartingBillingCycle = 5,
UnitAmountInCents = 1000
}
};
var change = new SubscriptionChange()
{
UnitAmountInCents = 100
// or, for ramp-priced subscriptions:
// RampIntervals = newRampIntervals
};
var newSub = Subscription.PreviewChange(subUuid, change);
"/subscriptions/{uuid}/convert_trial":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Convert Trial
description: |+
Convert a trial to a paid subscription.
tags:
- subscriptions
operationId: convertTrial
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:10:54Z2016-09-03T16:02:24Z2016-08-03T16:10:54Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z2016-07-03T16:02:24Z2016-08-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trial1
sizelarge
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingConvertTrialResponse"
x-codeSamples:
- lang: PHP
source: >-
convertTrial();
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('37bfef7a8e44cfc3817b7a43eba8a6e6')
subscription.convert_trial
- lang: Python
source: |-
subscription = Subscription.get('37bfef7a8e44cfc3817b7a43eba8a6e6')
subscription.convert_trial()
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("37bfef7a8e44cfc3817b7a43eba8a6e6");
subscription.ConvertTrial();
"/subscriptions/{uuid}/pause":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Pause Subscription
description: >-
Schedule a pause or update remaining pause cycles for a subscription.
Use this endpoint to:
* Schedule a subscription pause on an active subscription
* Update the pause period length on a subscription with a scheduled pause or a subscription paused already.
* Cancel a scheduled pause on a pending pause subscription
For an active subscription without a pause scheduled already, this will schedule a pause period to begin at the next bill date for the specified number of billing cycles (remaining_pause_cycles).
When a scheduled pause already exists, this will update the remaining pause cycles with the new value sent. When zero (0) remaining_pause_cycles is sent for a subscription with a scheduled pause, the pause will be canceled.
For a paused subscription, the remaining_pause_cycles will adjust the length of the current pause period. Sending zero (0) in the remaining_pause_cycles field will cause the subscription to be resumed at the next bill date.
tags:
- subscriptions
operationId: pauseSubscription
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- remaining_pause_cycles
properties:
remaining_pause_cycles:
type: integer
default: ""
description: The number of billing cycles that the subscription will be paused
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:10:54Z2016-09-03T16:02:24Z2016-08-03T16:10:54Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trial1
sizelarge
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingPauseResponse"
x-codeSamples:
- lang: xml
source: |-
1
- lang: PHP
source: >-
pause(1);
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('37bfef7a8e44cfc3817b7a43eba8a6e6')
subscription.pause(1)
- lang: Python
source: |-
sub = Subscription.get('37bfef7a8e44cfc3817b7a43eba8a6e6')
sub.pause(1)
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("37bfef7a8e44cfc3817b7a43eba8a6e6");
subscription.Pause(1);
"/subscriptions/{uuid}/resume":
parameters:
- $ref: "#/components/parameters/subscription_uuid"
put:
summary: Resume Subscription
description: >-
Immediately reactivate a paused subscription, starting a new billing
cycle.
For a paused subscription, this will immediately resume the subscription from the pause, produce an invoice, and return the newly resumed subscription. Any at-term renewal subscription changes will be immediately applied when the subscription resumes.
tags:
- subscriptions
operationId: resumeSubscription
responses:
"200":
description: ""
content:
application/xml:
examples:
fixedPricing:
summary: Fixed Pricing
value: |-
goldGold planevenly37bfef7a8e44cfc3817b7a43eba8a6e6active4500EUR12016-08-03T16:02:24Z2016-08-03T16:10:54Z2016-09-03T16:02:24Z2016-08-03T16:10:54Z2016-08-03T16:02:24Z2016-09-03T16:02:24Z394usstCA0.08750netautomaticplan_free_trialsizelarge
rampPricing:
$ref: "#/components/examples/SubscriptionRampPricingResponse"
x-codeSamples:
- lang: PHP
source: >-
resume();
print "Subscription: $subscription";
} catch (Recurly_NotFoundError $e) {
print "Subscription Not Found: $e";
}
- lang: Ruby
source: >-
subscription =
Recurly::Subscription.find('37bfef7a8e44cfc3817b7a43eba8a6e6')
subscription.resume()
- lang: Python
source: |-
sub = Subscription.get('37bfef7a8e44cfc3817b7a43eba8a6e6')
sub.resume()
- lang: Dotnet
source: >-
var subscription =
Subscriptions.Get("37bfef7a8e44cfc3817b7a43eba8a6e6");
subscription.Resume();
"/measured_units":
get:
summary: List Measured Units
description: |+
List all measured units for your site.
tags:
- measured-units
operationId: listMeasuredUnits
parameters: []
responses:
"200":
description: ""
content:
application/xml:
example: >-
454087618196407477Ad ImpressionsImpressionNumber of ad impressions12345678901234567890Streaming BandwidthGBVideo steaming bandwidth measured in gigabytes
x-codeSamples:
- lang: PHP
source: |-
-
12345678901234567890Streaming BandwidthGBVideo steaming bandwidth measured in gigabytes
schema:
$ref: "#/components/schemas/MeasuredUnit"
x-codeSamples:
- lang: xml
source: >-
Streaming BandwidthGBVideo steaming bandwidth measured in gigabytes
- lang: PHP
source: >-
name = 'Streaming Bandwidth';
$unit->display_name = 'GB';
$unit->description = 'Video steaming bandwidth measured in gigabytes';
$unit->create();
- lang: Ruby
source: |-
# Create MeasuredUnit
measured_unit = Recurly::MeasuredUnit.new(
name: "Streaming Bandwidth",
display_name: "GB",
description: "Video steaming bandwidth measured in gigabytes"
)
measured_unit.save
puts measured_unit
- lang: Python
source: >-
from recurly import MeasuredUnit
# Create a Measured unit
measured_unit = MeasuredUnit(
name="Streaming Bandwidth",
display_name="GB",
description="Video steaming bandwidth measured in gigabytes")
measured_unit.save()
print measured_unit
- lang: Dotnet
source: >-
var measuredUnit = new MeasuredUnit("Streaming Bandwidth", "GB",
"Video steaming bandwidth measured in gigabytes");
measuredUnit.Create();
"/measured_units/{measured_unit_id}":
get:
summary: Lookup Measured Unit
description: >+
Lookup a specific measured unit for your site. A customer's usage-based
add-on and usage records will reference the associated measured unit
where you can grab the display name for pricing and usage displays.
tags:
- measured-units
operationId: lookupMeasuredUnit
parameters:
- in: path
name: measured_unit_id
schema:
type: string
default: ""
required: true
description: Unique id of the measured unit on your site.
responses:
"200":
description: ""
content:
application/xml:
example: >-
454087618196407477Ad ImpressionsImpressionNumber of ad impressions
schema:
$ref: "#/components/schemas/MeasuredUnit"
x-codeSamples:
- lang: PHP
source: |-
+
Update a measured unit on your site. Updates immediately change the
measured unit for any associated plan and subscription usage-based
add-ons.
tags:
- measured-units
operationId: updateMeasuredUnit
parameters:
- in: path
name: measured_unit_id
schema:
type: string
default: ""
required: true
description: Unique id of the measured unit on your site.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
name:
type: string
default: ""
description: Unique internal name of the measured unit on your site.
display_name:
type: string
default: ""
description:
Display name for the measured unit. We recommend the singular
version. (e.g. - GB, API Call, Email).
description:
type: string
default: ""
description: Optional internal description.
responses:
"200":
description: ""
content:
application/xml:
example: >-
12345678901234567890Streaming BandwidthGigabyteVideo steaming bandwidth measured in gigabytes
schema:
$ref: "#/components/schemas/MeasuredUnit"
x-codeSamples:
- lang: xml
source: |-
Gigabyte
- lang: Ruby
source: |-
measured_unit = Recurly::MeasuredUnit.find '12345678901234567890'
measured_unit.display_name = "Gigabyte"
measured_unit.save!
- lang: Dotnet
source: |-
var measuredUnit = MeasuredUnits.Get(12345678901234567890);
measuredUnit.DisplayName = "Gigabyte";
measuredUnit.Update();
delete:
summary: Delete Measured Unit
description: >+
Delete a measured unit on your site. The measured unit must be removed
from all plans before it can be deleted.
tags:
- measured-units
operationId: deleteMeasuredUnit
parameters:
- in: path
name: measured_unit_id
schema:
type: string
default: ""
required: true
description: Unique id of the measured unit on your site.
responses:
"204":
description: ""
content:
application/xml:
example: ""
x-codeSamples:
- lang: Ruby
source: |-
measured_unit = Recurly::MeasuredUnit.find(12345678901234567890)
measured_unit.destroy
- lang: Python
source: |-
measured_unit = recurly.MeasuredUnit.get(12345678901234567890)
measured_unit.delete()
- lang: Dotnet
source: |-
var measuredUnit = MeasuredUnits.Get(12345678901234567890);
measuredUnit.Delete();
"/subscriptions/{subscription_uuid}/add_ons/{add_on_code}/usage":
get:
summary: List Subscription Add-On's Usage
description: >+
Query on billed and unbilled usage for your customer's usage-based
add-on.
tags:
- subscription-usage-records
operationId: listSubscriptionAddOnsUsage
parameters:
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: billing_status
schema:
type: string
default: unbilled
description:
"`all`, `unbilled`, or `billed`. Defines whether or not to include
usage records with a `billed_at` date."
- in: query
name: datetime_type
schema:
type: string
default: usage
description:
"`usage` or `recording`. Whether you would like to filter on the
`usage_timestamp` or the `recording_timestamp`."
- in: query
name: start_datetime
schema:
type: string
format: date-time
default: ""
description: Show usage records greater than or equal to this date.
- in: query
name: end_datetime
schema:
type: string
format: date-time
default: ""
description: Show usage records less than this date.
- in: path
name: subscription_uuid
schema:
type: string
default: ""
required: true
description: Subscription's unique identifier.
- in: path
name: add_on_code
schema:
type: string
default: ""
required: true
description: The unique add-on code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
1Order ID: 49398539778787132016-07-14T13:09:15+00:002016-07-14T22:30:15+00:002016-07-14T22:33:17+00:00price45
"400":
description: Add-On Not Found
content:
application/xml:
example: >-
not_foundCouldn't find AddOn with add_on_code = video_streaming
x-codeSamples:
- lang: PHP
source: >
"all",
//"datetime_type" => "usage",
//"start_datetime" => datetime,
//"end_datetime" => datetime,
);
// $params is optional
$usages = $subscription->usages('marketing_emails', $params);
print count($usages);
foreach ($usages as $usage) {
print $usage->merchant_tag . "\n";
}
- lang: Ruby
source: >-
# You need a subscription_add_on that you want find usages for
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
sub_add_on = subscription.subscription_add_ons.detect do |add_on|
add_on.add_on_code == 'marketing_emails'
end
search_options = {
billing_status: :all, # (:all || :unbilled || :billed)
datetime_type: :usage, # optional (:usage || :recording)
start_datetime: DateTime.now, # optional starting datetime
end_datetime: DateTime.now, # optional ending datetime
}
# the search_options hash is optional
pager = sub_add_on.usage.paginate(search_options)
pager.find_each do |usage|
puts usage.inspect
end
- lang: Python
source: >-
from recurly import Subscription
# You need a subscription_add_on that you want to find usages for
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
# Let's just choose the first one, could filter by add_on_code
sub_add_on = subscription.subscription_add_ons[0]
search_options = {
'billing_status': 'all', # (all or unbilled or billed)
'datetime_type': 'usage', # optional (usage or recording)
'start_datetime': datetime.datetime.now(), # optional starting datetime
'end_datetime': datetime.datetime.now(), # optional ending datetime
}
# the search_options dict is optional
filtered_usages = sub_add_on.usage(**search_options)
for usage in filtered_usages:
print usage
- lang: Dotnet
source: |-
var subscriptionUuid = "37bfef7a8e44cfc3817b7a43eba8a6e6";
var subscriptionAddOnCode= "ip_addresses";
var usages = Usage.List(subscriptionUuid, subscriptionAddOnCode);
while (usages.HasAny())
{
foreach (var u in usages)
Console.WriteLine("Usage: " + u.Amount);
usages = usages.Next;
}
post:
summary: Log Usage
description: "Log usage to your customer's purchased usage based add-ons.
###### ATTENTION:
If you'd like to set `usage_timestamp` or `recording_timestamp`
to \"now,\" please leave those fields blank. This will allow the server
to set the values. Manually setting `usage_timestamp` and/or
`recording_timestamp` to \"now\" has been known to trigger the following
error when clocks get skewed: \"Cannot create usage record with a usage
timestamp in the future.\"
\ "
tags:
- subscription-usage-records
operationId: logUsage
parameters:
- in: path
name: subscription_uuid
schema:
type: string
default: ""
required: true
description: Subscription's unique identifier.
- in: path
name: add_on_code
schema:
type: string
default: ""
required: true
description: The unique add-on code.
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- amount
properties:
amount:
type: integer
default: ""
description:
The amount of usage. Can be positive, negative, or 0. If the
Decimal Quantity feature is enabled, this value will be rounded to nine
decimal places. Otherwise, all digits after the decimal will be stripped.
If the usage-based add-on is billed with a percentage, your usage should
be a monetary amount formatted in cents (e.g., $5.00 is "500").
merchant_tag:
type: string
default: ""
description:
Custom field great for recording the id in your own system
associated with the usage, so you can provide auditable
usage displays to your customers using a GET on this
endpoint.
recording_timestamp:
type: string
format: date-time
default: usage_timestamp value
description:
When the usage was recorded in your system. Defaults to current
timestamp.
usage_timestamp:
type: string
format: date-time
default: ""
description:
When the usage actually happened. This will define the line item
dates this usage is billed under and is important for
revenue recognition. Defaults to current timestamp.
responses:
"201":
description: ""
content:
application/xml:
example: >-
1Order ID: 49398539778787132016-07-14T13:09:15+00:002016-07-14T22:30:15+00:002016-07-14T22:33:17+00:00price4515213266691581559491Batch of 100 marketing emails sent by customer2020-07-31T00:44:31Z2020-07-31T00:44:31Z2020-07-31T00:44:31Z2020-07-31T00:44:31Zprice0tiered200050009999999993500
schema:
$ref: "#/components/schemas/Usage"
"422":
description: Usage Timestamp Before/After Add-on Existed
content:
application/xml:
example: >-
is not within valid date range for the subscription
x-codeSamples:
- lang: xml
source: |-
1Order ID: 49398539778787132016-07-14T13:09:15Z2016-07-14T22:30:15Z
- lang: PHP
source: >-
create();
- lang: Ruby
source: >-
# You need a subscription_add_on that you want to bill usage on
subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')
sub_add_on = subscription.subscription_add_ons.detect do |add_on|
add_on.add_on_code == 'marketing_emails'
end
usage1 = sub_add_on.usage.build(
amount: 100,
merchant_tag: "Batch of 100 marketing emails sent by customer",
recording_timestamp: DateTime.now,
usage_timestamp: DateTime.now
)
usage1.save!
# You can create instead of build
usage2 = sub_add_on.usage.create!(
amount: 200,
merchant_tag: "Batch of 200 marketing emails sent by customer",
recording_timestamp: DateTime.now,
usage_timestamp: DateTime.now
)
- lang: Python
source: |-
from recurly import Subscription, Usage
# You need a subscription_add_on that you want to bill usage on
subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')
# Let's just choose the first one, could filter by add_on_code
sub_add_on = subscription.subscription_add_ons[0]
usage = Usage()
usage.amount = 100 # record 100 emails
usage.merchant_tag = "Recording 100 emails used by customer"
usage.recording_timestamp = datetime.datetime.utcnow()
usage.usage_timestamp = datetime.datetime.utcnow()
subscription.create_usage(sub_add_on, usage)
- lang: Dotnet
source: |-
var subUuid = "374ae5e848adcfd332fdd3469d89c888";
var addOnCode = "video_streaming";
var usage = new Usage(subUuid, addOnCode);
usage.Amount = 1;
usage.UsageTimestamp = DateTime.Now;
usage.Create();
"/subscriptions/{subscription_uuid}/add_ons/{add_on_code}/usage/{usage_id}":
get:
summary: Lookup Usage Record
description: |+
Lookup a specific usage record.
tags:
- subscription-usage-records
operationId: lookupUsageRecord
parameters:
- in: path
name: subscription_uuid
schema:
type: string
default: ""
required: true
description: Subscription's unique identifier.
- in: path
name: add_on_code
schema:
type: string
default: ""
required: true
description: The unique add-on code.
- in: path
name: usage_id
schema:
type: string
default: ""
required: true
description: Unique id for the usage record.
responses:
"200":
description: ""
content:
application/xml:
example: >-
1Order ID: 49398539778787132016-07-14T13:09:15+00:002016-07-14T22:30:15+00:002016-07-14T22:33:17+00:00price45152134048546396752722020-07-31T01:11:58Z2020-07-31T01:11:58Z2020-07-31T01:11:58Z2020-07-31T01:11:58Zprice0tiered609999999999950152134048546396752722020-07-31T01:11:58Z2020-07-31T01:11:58Z2020-07-31T01:11:58Z2020-07-31T01:11:58Zpercentagetiered1000010.020.0
schema:
$ref: "#/components/schemas/Usage"
x-codeSamples:
- lang: PHP
source: >-
+
Mistakes happen. If you find a usage mistake before it is billed, you
can update the record. After it is billed you can only update the
merchant_tag.
tags:
- subscription-usage-records
operationId: updateUsageRecord
parameters:
- in: path
name: subscription_uuid
schema:
type: string
default: ""
required: true
description: Subscription's unique identifier.
- in: path
name: add_on_code
schema:
type: string
default: ""
required: true
description: The unique add-on code.
- in: path
required: true
name: usage_id
schema:
type: string
default: ""
description: Unique id for the usage record.
requestBody:
required: true
content:
application/xml:
schema:
type: object
properties:
amount:
type: integer
default: ""
description: Only allowed if `billed_at` is `null`.
merchant_tag:
type: string
default: ""
description: Can be updated anytime.
recording_timestamp:
type: string
format: date-time
default: usage_timestamp value
description: Only allowed if `billed_at` is `null`.
usage_timestamp:
type: string
format: date-time
default: ""
description: Only allowed if `billed_at` is `null`.
responses:
"200":
description: ""
content:
application/xml:
example: >-
24Order ID: 49398539778787132016-07-14T13:09:15+00:002016-07-14T22:30:15+00:002016-07-14T22:33:17+00:002016-07-14T22:45:56+00:00price45
schema:
$ref: "#/components/schemas/Usage"
x-codeSamples:
- lang: xml
source: |-
2
- lang: PHP
source: >-
amount = 2;
$usage->update();
- lang: Dotnet
source: >-
var usage = Usages.Get("374ae5e848adcfd332fdd3469d89c888",
"video_streaming", 450646065398417338);
usage.Amount = 2;
usage.Update();
- lang: Ruby
source: "usage.update_attributes(amount: 2)"
- lang: Python
source: |-
usage.amount = 2
usage.save()
delete:
summary: Delete Usage Record
description: >+
Mistakes happen. If you find a usage mistake before it is billed, you
can delete the record. After it is billed you cannot delete the record
and will want to create a new usage record to counteract the billed
usage amount on the account.
tags:
- subscription-usage-records
operationId: deleteUsageRecord
parameters:
- in: path
name: subscription_uuid
schema:
type: string
default: ""
required: true
description: Subscription's unique identifier.
- in: path
name: add_on_code
schema:
type: string
default: ""
required: true
description: The unique add-on code.
- in: path
name: usage_id
schema:
type: string
default: ""
required: true
description: Unique id for the usage record.
responses:
"204":
description: Successful Delete
content:
application/xml:
example: ""
x-codeSamples:
- lang: Dotnet
source: >-
var usage = Usages.Get("374ae5e848adcfd332fdd3469d89c888",
"video_streaming", 450646065398417338);
usage.Delete();
"/transactions":
get:
summary: List Transactions
description: "\n\n"
tags:
- transactions
operationId: listTransactions
parameters:
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of transactions to return: `successful`, `failed`, or
`voided`."
- in: query
name: type
schema:
type: string
default: ""
description:
"The type of transactions to return: `authorization`, `refund`, or
`purchase`."
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
example: >-
374adcf4d716c1afc7b0b64bb79d438dpurchase1099USDsuccesscredit_card2216615transactionfalsetruetruetrue127.0.0.1Street address and postal code match.2016-07-11T22:26:35Z2016-07-11T22:26:35Z1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124111111111
x-codeSamples:
- lang: PHP
source: |-
-
using System.Linq;
var transactions = Transactions.List();
while (transactions.Any())
{
foreach (var transaction in transactions)
Console.WriteLine("Transaction: " + transaction);
transactions = transactions.Next;
}
// Filter successful Transactions
var transactions = Transactions.List(TransactionList.TransactionState.Success);
// Filter failed purchases
var transactions = Transactions.List(TransactionList.TransactionState.Success,
TransactionList.TransactionType.Failed);
post:
summary: Create Transaction
description: >-
The endpoint provides a shortcut for creating an invoice, charge, and
optionally account, and processing the payment immediately. When
creating an account all of the required account attributes must be
supplied. When charging an existing account only the `account_code` must
be supplied.
###### Deprecated in favor of Purchases
We recommend use the [Create Purchase](/docs/create-purchase) endpoint instead of this one. With it you can create an account, billing info, multiple charges, credits and subscriptions, and invoice and collect payment processed in one step.
##### Using Stored Billing Info
You may create a transaction without specifying billing information if an account already has stored billing information.
```csharp
var transaction = new Transaction("1", 100, "USD"); // account code, unit amount in cents, currency
transaction.Create();
```
##### Using Existing Billing Info
After a successful transaction, the billing information will be saved with the account for future purchases. If the account already has stored billing info, the billing info from the last transaction overwrite the previous values.
xml
PHP
Ruby
Python
Dotnet
```xml
1000USD1VerenaExample123 Main St.San Francisco94105US4111-1111-1111-1111123112015
```
```csharp
var account = Accounts.Get("1");
account.BillingInfo = new BillingInfo(account.AccountCode)
{
FirstName = "Verana",
LastName = "Example",
CreditCardNumber = "4111-1111-1111-1111",
VerificationValue = "123",
ExpirationYear = 2015,
ExpirationMonth = 11
};
var transaction = new Transaction(account, 100, "USD");
transaction.Create();
```
tags:
- transactions
operationId: createTransaction
parameters: []
requestBody:
required: true
content:
application/xml:
schema:
type: object
required:
- amount_in_cents
- currency
- account
- account_code
- first_name
- last_name
- billing_info
- number
- month
- year
properties:
amount_in_cents:
type: integer
default: ""
description: Amount of the transaction in cents. Max 10000000.
currency:
type: string
default: ""
description: 3-letter currency for the transaction
account:
type: object
default: ""
description: nested attributes (see below)
account_code:
type: string
default: ""
description:
"A unique identifier used by your application to identify the
account. This code may only contain the following
characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters."
description:
type: string
default: ""
description:
A description for the transaction. Description is added to the
invoiced charge, and not the transaction object
username:
type: string
default: ""
description: Username, ignore if you do not use usernames
email:
type: string
default: ""
description: Email address
first_name:
type: string
default: ""
description: First Name. Max 50 characters.
last_name:
type: string
default: ""
description: Last Name. Max 50 characters.
company_name:
type: string
default: ""
description: Company name. Max of 50 characters.
accept_language:
type: string
default: ""
description:
An ISO 639-1 language code from the user's browser, indicating
their preferred language and locale.
billing_info:
type: object
default: ""
description: account->billing_info nested attributes (see below)
company:
type: string
default: ""
description: Company name. Max of 50 characters.
address1:
type: string
default: ""
description:
Address line 1, recommended for address validation. Max 50
characters.
address2:
type: string
default: ""
description: Address line 2. Max 50 characters.
city:
type: string
default: ""
description: City. Max 50 characters. Strongly Recommended
state:
type: string
default: ""
description: State or Province, 2-letters preferred
country:
type: string
default: ""
description: Country, 2-letter ISO code. Strongly Recommended
zip:
type: string
default: ""
description:
Zip or postal code, recommended for address validation. Strongly
Recommended
phone:
type: string
default: ""
description: Phone number
vat_number:
type: string
default: ""
description: Customer's VAT Number
ip_address:
type: string
default: ""
description:
Customer's IP address when updating their billing information.
Strongly Recommended.
number:
type: string
default: ""
description: Credit card number, spaces and dashes are accepted.
month:
type: string
default: ""
description: Expiration Month
year:
type: string
default: ""
description: Expiration Year
verification_value:
type: string
default: ""
description: Security code or CVV, 3-4 digits. Strongly Recommended.
accounting_code:
type: string
default: ""
description: Accounting code. Max of 20 characters.
tax_exempt:
type: boolean
default: "false"
description:
"`true` exempts tax on the charge, `false` applies tax on the
charge. If not defined, defaults to `false`."
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box
tax solution to determine taxation rules. You can pass in specific tax codes
using any of these tax integrations. For Recurly's In-the-Box tax offering
you can also choose to instead use simple values of `unknown`, `physical`, or
`digital` tax codes.
product_code:
type: string
default: ""
description:
"The product code or SKU of the line item. Max of 50 characters.
Useful for later reporting on product purchases. Note: this
will not be returned in the create transaction response, but
it will show on the associated adjustment object if it was
set while creating a transaction."
responses:
"201":
description: ""
content:
application/xml:
example: >-
374adcf4d716c1afc7b0b64bb79d438dpurchase1099USDsuccesscredit_card2216615transactionfalsetruetruetrue127.0.0.1Street address and postal code match.2016-07-11T22:26:35Z2016-07-11T22:26:35Z1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124111111111
{"type": "redirect", "url": "https://example.test/confirm"}
schema:
$ref: "#/components/schemas/Transaction"
"422":
description: ""
content:
application/xml:
example: >-
declined_saveablegeneric_declinesoftThe transaction was declined without specific information. Please contact your payment gateway for more details or ask the customer to contact their bank.The transaction was declined. Please use a different card or contact your bank.The transaction was declined. Please use a different card or contact your bank.3c42a4dc4ee4c81ed3795a415b92aa22purchase1099USDdeclinedcredit_card3922896transactionfalsetruefalsefalse127.0.0.1declined_saveablegeneric_declinesoftThe transaction was declined without specific information. Please contact your payment gateway for more details or ask the customer to contact their bank.The transaction was declined. Please use a different card or contact your bank.2017-03-15T21:22:18Z2017-03-15T21:22:18Z1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124000000341
x-codeSamples:
- lang: xml
source: |-
// Example with Stored Billing Info
100USD1
// Example with new Billing Info
1000USD1VerenaExample123 Main St.San Francisco94105US4111-1111-1111-1111123112015
- lang: PHP
source: |-
amount_in_cents = 1000; // $10.00.
$transaction->currency = 'USD';
$account = new Recurly_Account();
$account->account_code = '1';
$billing_info = new Recurly_BillingInfo();
$billing_info->first_name = 'Verena';
$billing_info->last_name = 'Example';
$billing_info->number = '4111-1111-1111-1111';
$billing_info->verification_value = '123';
$billing_info->month = 11;
$billing_info->year = 2015;
$account->billing_info = $billing_info;
$transaction->account = $account;
$transaction->create();
- lang: Ruby
source: |-
transaction = Recurly::Transaction.create(
:amount_in_cents => 10_00,
:currency => 'USD',
:account => {
:account_code => '1',
:billing_info => {
:first_name => 'Verena',
:last_name => 'Example',
:number => '4111-1111-1111-1111',
:verification_value => '123',
:month => 11,
:year => 2015
}
}
)
- lang: Python
source: |-
transaction = Transaction(
amount_in_cents=1000,
currency='USD',
account=Account(
account_code=account_code,
billing_info=BillingInfo(
first_name='Verena',
last_name='Example',
number='4111-1111-1111-1111',
verification_value='123',
year=2015',
month=11
)
)
)
transaction.save()
- lang: Dotnet
source: |-
var account = Accounts.Get("1");
account.BillingInfo = new BillingInfo(account.AccountCode)
{
FirstName = "Verana",
LastName = "Example",
CreditCardNumber = "4111-1111-1111-1111",
VerificationValue = "123",
ExpirationYear = 2015,
ExpirationMonth = 11
};
var transaction = new Transaction(account, 100, "USD");
transaction.Create();
"/accounts/{account_code}/transactions":
get:
summary: List Account's Transactions
description: "\n\n"
tags:
- transactions
operationId: listAccountsTransactions
parameters:
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: Account's unique code.
- in: query
name: state
schema:
type: string
default: ""
description:
"The state of transactions to return: `successful`, `failed`, or
`voided`."
- in: query
name: type
schema:
type: string
default: ""
description:
"The type of transactions to return: `authorization`, `refund`, or
`purchase`."
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
responses:
"200":
description: ""
content:
application/xml:
example: >-
374adcf4d716c1afc7b0b64bb79d438dpurchase1099USDsuccesscredit_card2216615transactionfalsetruetruetrue127.0.0.1Street address and postal code match.2016-07-11T22:26:35Z2016-07-11T22:26:35Z1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124111111111
x-codeSamples:
- lang: PHP
source: |-
-
37bff9ddc1e468a59f6fef417cb32281refund87070EURsuccesscredit_card1171163subscriptionfalsetruetruefalseStreet address and postal code match.2016-08-03T16:13:44Z2016-08-03T16:13:44Z1VerenaExampleRecurly Incverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124111111111
schema:
$ref: "#/components/schemas/Transaction"
x-codeSamples:
- lang: PHP
source: >-
-
3d3f6754c6df41b9d2a32e43029adc55paymentUSD10002017-07-06T15:51:38Z2017-07-06T15:51:38Z2017-07-22T15:51:38Z3d3f6754c6df41b9d2a32e43029adc55refundUSD10002017-07-06T15:51:38Z2017-07-06T15:51:38Z
x-codeSamples:
- lang: PHP
source: |-
3d3f6754c6df41b9d2a32e43029adc55refundUSD10002017-07-06T15:51:38Z2017-07-06T15:51:38Z
schema:
$ref: "#/components/schemas/CreditPayment"
x-codeSamples:
- lang: Ruby
source: >-
begin
credit_payment = Recurly::CreditPayment.find '3e8764beb04add789fb3b54778838e17'
puts "Credit Payment: #{credit_payment.inspect}"
rescue Recurly::Resource::NotFound => e
puts e.message
end
- lang: Python
source: >-
try:
payment = recurly.CreditPayment.get('3e8764beb04add789fb3b54778838e17')
print("Credit Payment: %s" % payment)
except recurly.NotFoundError:
print("Credit Payment not found.\n")
- lang: Dotnet
source: >-
try
{
var creditPayment = CreditPayments.Get("3e8764beb04add789fb3b54778838e17");
Console.WriteLine("Credit Payment " + creditPayment);
}
catch (NotFoundException e)
{
Console.WriteLine("CreditPayment not found.");
}
"/accounts/{account_code}/credit_payments":
get:
summary: List Credit Payments on Account
description: |+
List credit payments associated with a specific account.
tags:
- credit-payments
operationId: listCreditPaymentsOnAccount
parameters:
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: path
name: account_code
schema:
type: string
default: ""
required: true
description: The account's account_code.
responses:
"200":
description: ""
content:
application/xml:
example: >-
3d3f6754c6df41b9d2a32e43029adc55paymentUSD10002017-07-06T15:51:38Z2017-07-06T15:51:38Z2017-07-22T15:51:38Z3d3f6754c6df41b9d2a32e43029adc55refundUSD10002017-07-06T15:51:38Z2017-07-06T15:51:38Z
x-codeSamples:
- lang: PHP
source: |-
+
This endpoint returns a list of the dates for which there are exports
are available. This provides you with historical information about what
data is available.
Note: This endpoint requires some configuration. Refer to [our docs](https://docs.recurly.com/v1.0/docs/export-overview#section-automated-exports) for more information on configuring your site for Automated Exports.
tags:
- exports
operationId: listExportDates
parameters: []
responses:
"200":
description: ""
content:
application/xml:
example: >-
2016-08-01
"404":
description: ""
content:
application/xml:
example: |-
not_found404 Resource Not Found
x-codeSamples:
- lang: PHP
source: |-
date}\n");
}
- lang: Python
source: |-
for export_date in recurly.ExportDate.all():
print 'Export Date: %s' % export_date
"/export_dates/{date}/export_files":
get:
summary: List Date's Export Files
description: >+
Returns a list of the specific exports available for the date specified.
This provides you with historical information about what data is
available.
Note: This endpoint requires some configuration. Refer to [our docs](https://docs.recurly.com/v1.0/docs/export-overview#section-automated-exports) for more information on configuring your site for Automated Exports.
tags:
- exports
operationId: listDatesExportFiles
parameters:
- in: path
name: date
schema:
type: string
format: date
default: ""
required: true
description: The date the export file was generated in YYYY-MM-DD format.
responses:
"200":
description: ""
content:
application/xml:
example: >-
revenue_schedules_full.csv9aa55980167ae522b27410edcd5303b0
"404":
description: ""
content:
application/xml:
example: |-
not_found404 Resource Not Found
x-codeSamples:
- lang: PHP
source: |-
md5sum}\t{$file->name}\t{$file->getHref()}\n");
}
- lang: Python
source: |-
for export_file in recurly.ExportDate().files("2016-08-01"):
print("Export file: %s" % export_file)
"/export_dates/{date}/export_files/{file_name}":
get:
summary: Get Export File URL
description:
"This endpoints returns a temporary URL where you can download the
requested export file for the indicated date.\
Note: This endpoint requires some configuration. Refer to [our
docs](https://docs.recurly.com/v1.0/docs/export-overview#section-automa\
ted-exports) for more information on configuring your site for Automated
Exports.
###### Automated Exports
This feature must first be configured for your site via the
admin console before exports are available for download via this
endpoint. More information about how to set up this feature is
available in the product documentation - [Automated
Exports](https://docs.recurly.com/docs/export-overview#section-automate\
d-exports)
\ * If the nightly data is not yet fully available for
download, the endpoint will return a 404.\
\ * If you are unsure of what data is available for download,
this information is available via the List Exports
dates (export_dates) and List Dates's exports (export_files)
endpoints.\
\ * The secure URL returned from this endpoint will be active
for 60 minutes. After this time, a new authentication request must be
sent.\
\ * The secure URL returned from this endpoint will provide
access to the requested individual export for the requested date.
\ "
tags:
- exports
operationId: downloadExportFile
parameters:
- in: path
name: date
schema:
type: string
format: date
default: ""
required: true
description: The date the export file was generated.
- in: path
name: file_name
schema:
type: string
default: ""
required: true
description: The name of the export file.
responses:
"200":
description: ""
content:
application/xml:
example: >-
2016-08-19T18:32:06Zhttps://recurly-download-url.com/freightliner/1234567890/dates/2016-09-27/download_file.csv.gz?AWSAccessKeyId=KEY&Expires=1471631526&Signature=ttIDgi25oQLHo7jrj%2BU83GzipIQ%3D
"404":
description: ""
content:
application/xml:
example: |-
not_found404 Resource Not Found
x-codeSamples:
- lang: PHP
source: >-
download($fp);
fclose($fp);
- lang: Python
source: |-
export_date_files = recurly.ExportDate().files("2016-08-01")
url = export_date_files[0].download_information().download_url
# Download your data somehow with the URL
print(url)
"/shipping_methods":
get:
summary: List Shipping Methods
description: >+
For additional information regarding shipping methods, please see
https://docs.recurly.com/docs/shipping
tags:
- shipping-fees
operationId: listShippingMethods
parameters:
- in: query
name: cursor
schema:
type: string
default: ""
description:
Splits records across pages. Leave blank to return the first page.
Follow the URI in the first page's Link header to fetch the next
page.
- in: query
name: sort
schema:
type: string
default: created_at
description:
"The attribute that will be used to order records: `created_at`,
`updated_at`."
- in: query
name: order
schema:
type: string
default: desc
description:
"The order in which products will be returned: `asc` for ascending
order, `desc` for descending order."
- in: query
name: begin_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes greater than or equal
to the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: end_time
schema:
type: string
format: date-time
default: ""
description:
Operates on the attribute specified by the sort parameter. Filters
records to only include those with datetimes less than or equal to
the supplied datetime. Accepts an ISO 8601 date or date and time.
- in: query
name: per_page
schema:
type: integer
default: "50"
description: Number of records to return per page, up to a maximum of 200.
responses:
"200":
description: ""
content:
application/xml:
example: >-
shippingShippingt5ejtgf1vxt5ejtgf2rft5ejtge1xw2019-05-03T23:16:05Z2019-05-03T23:16:05Zslow_boatSlow Boatt5ejtgf1vxt5ejtgf2rft5ejtge1xw2019-05-04T16:36:22Z2019-05-04T16:36:22Z
x-codeSamples:
- lang: PHP
source: |-
name\n");
}
- lang: Ruby
source: >-
Recurly::ShippingMethod.find_each(per_page: 200) do
|shipping_method|
puts shipping_method.code
end
- lang: Python
source: >-
page_size = 200
for shipping_method in recurly.ShippingMethod.all(per_page = page_size):
print(shipping_method.name)
- lang: Dotnet
source: >-
using System.Linq;
var shippingMethods = ShippingMethods.List();
while (shippingMethods.Any())
{
foreach (var shippingMethod in shippingMethods)
Console.WriteLine("Shipping Method: " + shippingMethod.Name);
shippingMethods = shippingMethods.Next;
}
"/shipping_methods/{shipping_method_code}":
get:
summary: Lookup Shipping Method
description: >+
For additional information regarding shipping methods, please see
https://docs.recurly.com/docs/shipping
tags:
- shipping-fees
operationId: lookupShippingMethod
parameters:
- in: path
required: true
name: shipping_method_code
schema:
type: string
default: ""
description: Unique code to identify a shipping method.
responses:
"200":
description: ""
content:
application/xml:
example: >-
fast_fast_fastFast Fast Fastt5ejtgf1vxt5ejtgf2rft5ejtge1xw2019-05-03T23:17:16Z2019-05-03T23:17:16Z
schema:
$ref: "#/components/schemas/ShippingMethod"
x-codeSamples:
- lang: PHP
source: |-
-
3722298505492673710planpackagewritablePackageValue can be 'Basic' or 'Premium'2023-01-23T19:02:40Z2023-01-23T19:02:47Z3717783227799104920chargesizeapi_only2023-01-17T13:31:37Z2023-01-17T13:31:37Z3704733972259271618chargecolorapi_only2022-12-30T13:25:04Z2022-12-30T13:25:04Z
"400":
description: Invalid or unpermitted parameter.
content:
application/xml:
schema:
"$ref": "#/components/schemas/RequestError"
example: |-
related_typerelated_type, must be account, subscription, item, plan, charge
"404":
description: Invalid site
content:
application/xml:
schema:
"$ref": "#/components/schemas/Errors"
example: |-
The subdomain ('your-subdomain') was not found
x-codeSamples:
- lang: PHP
source: |
# fetch all custom field definitions:
$custom_field_definitions = Recurly_CustomFieldDefinitionList::get();
# fetch all custom field definitions filtering by related type:
$custom_field_definitions = Recurly_CustomFieldDefinitionList::getByRelatedType('plan');
- lang: Python
source: |
# fetch all custom field definitions:
custom_field_definitions = recurly.CustomFieldDefinition.all()
# fetch all custom field definitions filtering by related type:
custom_field_definitions_for_plans = recurly.CustomFieldDefinition.all(related_type='plan')
- lang: Dotnet
source: |
# fetch all custom field definitions:
var customFieldDefinitions = CustomFieldDefinitions.List();
# fetch all custom field definitions filtering by related type:
var chargeCustomFieldDefinitions = CustomFieldDefinitions.List(CustomFieldDefinition.CustomFieldType.Charge);
- lang: Ruby
source: |
# fetch all custom field definitions:
Recurly::CustomFieldDefinition.find_each do |definition|
puts "Custom Field Definition: #{definition}"
end
# fetch all custom field definitions filtering by related type:
Recurly::CustomFieldDefinition.all(related_type: 'plan').each do |definition|
puts "Custom Field Definition: #{definition}"
end
"/custom_field_definitions/{custom_field_definition_id}":
get:
tags:
- custom_field_definition
operationId: get_custom_field_definition
summary: Fetch an custom field definition
parameters:
- "$ref": "#/components/parameters/custom_field_definition_id"
responses:
"200":
description: A custom field definition.
content:
application/xml:
schema:
"$ref": "#/components/schemas/CustomFieldDefinition"
example: >-
3722298505492673710planpackagewritablePackageValue can be 'Basic' or 'Premium'2023-01-23T19:02:40Z2023-01-23T19:02:47Z
"404":
description: Incorrect site or custom field definition ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/RequestError"
example: >-
not_foundCouldn't find Custom Field Definition with id 3722298505492673710
x-codeSamples:
- lang: PHP
source: $definition = Recurly_CustomFieldDefinition::get('3722298505492673710');
- lang: Python
source: |
custom_field_definition = recurly.CustomFieldDefinition.get('3722298505492673710')
- lang: Dotnet
source: |
var customFieldDefinition = CustomFieldDefinition.Get('3722298505492673710');
- lang: Ruby
source: |
definition = Recurly::CustomFieldDefinition.find('3722298505492673710')
puts "Custom Field Definition: ", definition
"/external_subscriptions":
get:
summary: Lists a Site's External Subscriptions
description: |+
Returns a list of all your external subscriptions that are managed by third-party platforms like Apple App Store
and Google Play Store.
tags:
- external-subscriptions
operationId: listExternalSubscriptions
responses:
"200":
description: ""
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalSubscription"
example: >-
7293239bae62777d8c1ae044a9843633rgybkg3d1l41apple-codeapple_app_store2022-08-29T19:29:58Z2022-10-18T17:20:24Z2022-07-24T14:15:22Zfalsefalsecom.foo.id1active2022-07-24T14:15:22Z2022-07-24T14:15:22Zfalsefalse2022-10-10T21:40:57Z2022-10-10T21:40:57Z
x-codeSamples:
- lang: PHP
source: |-
-
7293239bae62777d8c1ae044a9843633rgybkg3d1l41apple-codeapple_app_store2022-08-29T19:29:58Z2022-10-18T17:20:24Z2022-07-24T14:15:22Zfalsefalsecom.foo.id1active2022-07-24T14:15:22Z2022-07-24T14:15:22Z2022-10-10T21:40:57Z2022-10-10T21:40:57Z
schema:
$ref: "#/components/schemas/ExternalSubscription"
"404":
description: Incorrect site or external subscription ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalSubscription with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
7293239bae62777d8c1ae044a9843633rgybkg3d1l41apple-codeapple_app_store2022-08-29T19:29:58Z2022-10-18T17:20:24Z2022-07-24T14:15:22Zfalsefalsecom.foo.id1active2022-07-24T14:15:22Z2022-07-24T14:15:22Z2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: PHP
source: |-
-
su3f3uw6lj44new reference_code2google_play_store2023-05-04T17:01:17Z2023-05-08T20:59:35Z
"404":
description: Incorrect site or external product reference ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProductReference with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
"/external_products":
get:
summary: Lists a site's external products
description: |+
Returns a list of all your external products from an external resource that are not managed by the Recurly
platform and instead are managed by third-party platforms like Apple App Store and Google Play Store.
tags:
- external-products
operationId: listExternalProducts
responses:
"200":
description: ""
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalProduct"
example: >-
platinumPlatinum planExternal Product Name2022-08-25T22:00:32Z2022-10-10T21:40:50Zrgycreiyhs1qapple-codeapple_app_store2022-08-29T19:36:39Z2022-10-10T21:40:50Z
x-codeSamples:
- lang: PHP
source: |-
-
su4tr7jvxsxinewexternalproduct2023-05-01T16:52:53Z2023-05-01T16:52:53Zsthyvfjsjak4myrefcodegoogle_play_store2023-05-01T16:52:53Z2023-05-01T16:52:53Z
"404":
description: Not found
content:
application/xml:
example: >-
not_foundCouldn't find Plan with merchant_plan_id = fdieie
"422":
description: Unprocessable Entity
content:
application/xml:
example: >-
can't be blank
x-codeSamples:
- lang: xml
source: >-
newexternalproductmyplancodemyrefcodegoogle_play_store
- lang: PHP
source: >-
plan_code = 'p1';
$external_product->name = 'Cool Plan Name';
$external_product_reference = new Recurly_ExternalProductReference();
$external_product_reference->reference_code = 'reference_code';
$external_product_reference->external_connection_type = 'google_play_store';
$external_product->external_product_references = [$external_product_reference];
$external_product->create();
print "External Product created: $external_product\n";
} catch (Recurly_ValidationError $e) {
print "Invalid External Product data: $e";
}
- lang: Ruby
source: |-
external_product_info = (
{
:name => 'my-name',
:plan_code => 'my-plan-code',
:external_product_references => [Recurly::ExternalProductReference.new(external_connection_type: 'google_play_store', reference_code: 'my-reference-code')]
}
)
Recurly::ExternalProduct.create!(external_product_info)
- lang: Python
source: |-
external_product = ExternalProduct(
name = 'my-name'
plan_code = 'my-plan-code'
external_product_references = [
recurly.ExternalProductReference(
external_connection_type = 'google_play_store',
reference_code = 'my-reference-code'
)
]
)
external_product.save()
- lang: Dotnet
source: |-
var external_product = new ExternalProduct();
external_product.Name = "my-name";
external_product.PlanCode = "google_play_store";
external_product.ExternalProductReferences.Add(new ExternalProductReference('google_play_store', 'my-reference-code'))
external_product.Create();
"/external_products/{uuid}":
get:
summary: Fetch an External Product
description: |+
Returns a specific external product.
tags:
- external-products
operationId: fetchExternalProduct
parameters:
- in: path
name: uuid
schema:
type: string
default: ""
required: true
description: The uuid for the external product.
responses:
"200":
description: ""
content:
application/xml:
example: >-
platinumPlatinum planExternal Product Name2022-08-25T22:00:32Z2022-10-10T21:40:50Zrgycreiyhs1qapple-codeapple_app_store2022-08-29T19:36:39Z2022-10-10T21:40:50Z
schema:
$ref: "#/components/schemas/ExternalProduct"
"404":
description: Incorrect site or external product ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProduct with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
su4tr7jvxsxibasicplan5basicplan5myname2023-05-04T21:45:10Z2023-05-05T23:33:50Z
"400":
description: Bad Request
content:
application/xml:
example: >-
namecannot be provided for update
"404":
description: Not found
content:
application/xml:
example: >-
not_foundCouldn't find Plan with merchant_plan_id = fdieie
x-codeSamples:
- lang: xml
source: >-
myplancode
- lang: PHP
source: >-
uuid = 'swifdu8c9om9';
$external_product->plan_code = 'p1';
$external_product->update();
print "External Product updated: $external_product\n";
} catch (Recurly_ValidationError $e) {
print "Invalid External Product data: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('su4tr7jvxsxi')
external_product.plan_code = 'my-plan-code'
external_product.save
- lang: Python
source: |-
external_product = recurly.ExternalProduct.get('su4tr7jvxsxi')
external_product.plan_code = 'my-plan-code'
external_product.save()
- lang: Dotnet
source: |-
var external_product = ExternalProduct('su4tr7jvxsxi')
external_product.PlanCode= 'my-plan-code'
external_product.Update()
delete:
summary: Deactivate an External Product
tags:
- external-products
operationId: deactivateExternalProduct
parameters:
- in: path
name: uuid
schema:
type: string
default: ""
required: true
description: The uuid for the external product.
responses:
"204":
description: "Status: 204 No Content"
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find ExternalProduct with id
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swap0rbgpb1h';
$external_product->delete();
print "ExternalProduct $external_product->uuid removed" . PHP_EOL;
} catch (Recurly_ValidationError $e) {
print "Validation error: $e";
} catch (Recurly_Error $e) {
// Could not find external product
print "Bad request: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('p7gnbhfxbe8o')
external_product.destroy
- lang: Python
source: |-
external_product = ExternalProduct.get('p7gnbhfxbe8o')
external_product.delete()
- lang: Dotnet
source: |-
var external_product = ExternalProducts.Get("p7gnbhfxbe8o");
external_product.Delete();
"/external_products/{external_product_id}/external_product_references":
parameters:
- "$ref": "#/components/parameters/external_product_id"
get:
tags:
- external-product-references
operationId: listExternalProductExternalProductReference
summary: List external product references
responses:
"200":
description: Details for all external product references.
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalProductReference"
example: >-
su3f3uw6lj44new reference_code2google_play_store2023-05-04T17:01:17Z2023-05-08T20:59:35Z
"404":
description: Incorrect site or external product ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProduct with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swifdu8c9om9';
$external_product_references = $external_product->listExternalProductReferences();
foreach ($external_product_references as $external_product_reference) {
print "External Product Reference: $external_product_reference->reference_code\n";
}
} catch (Recurly_ValidationError $e) {
print "Validation error: $e";
} catch (Recurly_Error $e) {
// Could not find external product
print "Bad request: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('pbux7jvmauhe')
external_product_references = external_product.get_external_product_references
- lang: Python
source: |-
external_product = recurly.ExternalProduct.get("pbux7jvmauhe")
external_product_references = external_product.external_product_references
- lang: Dotnet
source: |-
var externalProduct = ExternalProduct.Get("pbux7jvmauhe");
var external_product_reference = externalProduct.GetExternalProductReferences();
post:
tags:
- external-product-references
operationId: createExternalProductExternalProductReference
summary: Create an external product reference
requestBody:
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalProductReferenceCreate"
required: true
responses:
"201":
description: Details for an external product reference.
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalProductReference"
example: >-
su3f3uw6lj44new reference_code2google_play_store2023-05-04T17:01:17Z2023-05-08T20:59:35Z
"404":
description: Incorrect site or external product ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProduct with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swarj00syoa9';
$external_product_reference = new Recurly_ExternalProductReference();
$external_product_reference->reference_code = 'reference_code2';
$external_product_reference->external_connection_type = 'apple_app_store';
$external_product->createExternalProductReference($external_product_reference);
print "External Product Reference created: $external_product_reference\n";
} catch (Recurly_ValidationError $e) {
print "Invalid External Product Reference data: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('pbux7jvmauhe')
new_external_product_reference = Recurly::ExternalProductReference.new(
external_connection_type: 'apple_app_store',
reference_code: 'abcd'
)
external_product.create_external_product_reference(new_external_product_reference)
- lang: Python
source: |-
external_product = recurly.ExternalProduct.get('pbux7jvmauhe')
external_product_reference = recurly.ExternalProductReference()
external_product_reference.external_connection_type = 'google_play_store'
external_product_reference.reference_code = 'abcd'
external_product.create_external_product_reference(external_product_reference)
- lang: Dotnet
source: |-
var externalProduct = ExternalProduct.Get('pbux7jvmauhe');
var externalProductReference = new ExternalProductReference();
externalProductReference.ExternalConnectionType = 'google_play_store';
externalProductReference.ReferenceCode = 'abcd';
externalProduct.CreateExternalProductReference(externalProductReference);
"/external_products/{external_product_id}/external_product_references/{external_product_reference_id}":
parameters:
- "$ref": "#/components/parameters/external_product_id"
- "$ref": "#/components/parameters/external_product_reference_id"
get:
tags:
- external-product-references
operationId: getExternalProductExternalProductReference
summary: Fetch an external product reference
responses:
"200":
description: Details for an external product reference.
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalProductReference"
example: >-
su3f3uw6lj44new reference_code2google_play_store2023-05-04T17:01:17Z2023-05-08T20:59:35Z
"404":
description: Incorrect site or external product reference ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProductReference with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swifdu8c9om9';
$external_product_reference = $external_product->getExternalProductReference("swifdua3cvtp");
print "External Product Reference: $external_product_reference->reference_code\n";
} catch (Recurly_ValidationError $e) {
print "Validation error: $e";
} catch (Recurly_Error $e) {
// Could not find external product
print "Bad request: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('pbux7jvmauhe')
external_product_reference = external_product.get_external_product_reference('pbux7jvmauhe')
- lang: Python
source: |-
external_product = recurly.ExternalProduct.get("pbux7jvmauhe")
external_product_reference = external_product.get_external_product_reference("pbux7jvmauhe")
- lang: Dotnet
source: |-
var externalProduct = ExternalProduct.Get("pbux7jvmauhe");
var external_product_reference = externalProduct.GetExternalProductReference("pbux7jvmauhe");
delete:
tags:
- external-product-references
operationId: deleteExternalProductExternalProductReference
summary: Deactivate an external product reference
responses:
"204":
description: No content.
"404":
description: Incorrect site or external product reference ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalProductReference with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swarj00syoa9';
$external_product->deleteExternalProductReference('swas4dl5xp3z');
print "ExternalProductReference swas4dl5xp3z removed" . PHP_EOL;
} catch (Recurly_ValidationError $e) {
print "Validation error: $e";
} catch (Recurly_Error $e) {
// Could not find external product
print "Bad request: $e";
}
- lang: Ruby
source: |-
external_product = Recurly::ExternalProduct.find('pbux7jvmauhe')
external_product_reference = external_product.get_external_product_reference('pbux7jvmasdf')
external_product_reference.destroy!
- lang: Python
source: |-
external_product = recurly.ExternalProduct.get("pbux7jvmauhe")
external_product_reference = external_product.get_external_product_reference("pbux7jvmauhe")
external_product_reference.delete()
- lang: Dotnet
source: |-
var externalProduct = ExternalProduct.Get("pbux7jvmauhe");
externalProduct.DeleteExternalProductReference("pbux7jvmauhe");
"/external_invoices":
get:
summary: Lists a Site's External Invoices
description: |+
See the [Pagination Guide](/developers/guides/pagination.html)
to learn how to use pagination in the API and Client Libraries.
tags:
- external-invoices
operationId: listExternalInvoices
responses:
"200":
description: ""
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalInvoice"
example: >-
external-idpaidUSD100scvf0zhrsjpureference-codeapple_app_store2023-02-06T19:56:18Z2023-02-06T19:56:18Z50USD12023-01-13T17:28:02Z2023-01-13T17:28:02Z2023-01-13T17:28:02Z2023-01-13T17:28:02Z<2024-10-10T21:40:57Z
x-codeSamples:
- lang: PHP
source: |-
-
external-idpaidUSD100scvf0zhrsjpureference-codeapple_app_store2023-02-06T19:56:18Z2023-02-06T19:56:18Z50USD12023-01-13T17:28:02Z2023-01-13T17:28:02Z2023-01-13T17:28:02Z2022-10-10T21:40:57Z2022-10-10T21:40:57Z
schema:
$ref: "#/components/schemas/ExternalInvoice"
"404":
description: Incorrect site or external invoice ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalInvoice with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
external-idpaidUSD100scvf0zhrsjpureference-codeapple_app_store2023-02-06T19:56:18Z2023-02-06T19:56:18Z50USD22023-02-07T18:53:55Z2023-02-07T18:53:55Z2023-01-13T17:28:02Z2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find Account with account_code
x-codeSamples:
- lang: PHP
source: |-
-
external-idpaidUSD100scvf0zhrsjpureference-codeapple_app_store2023-02-06T19:56:18Z2023-02-06T19:56:18Z50USD22023-02-07T18:53:55Z2023-02-07T18:53:55Z2023-01-13T17:28:02Z2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: Incorrect site or external subscription ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalSubscription with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
tws7x821sv1z2023-11-08T21:02:39Z2023-12-06T21:02:39Z141TWO_MONTHS0.0USD2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: Incorrect site or external subscription ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalSubscription with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
tws7x821sv1z2023-11-08T21:02:39Z2023-12-06T21:02:39Z141TWO_MONTHS0.0USD2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: Incorrect site, external subscription, or external payment phase ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalPaymentPhase with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
uuid = 'swifdu8c9om9';
$external_payment_phase = $external_subscription->getExternalPaymentPhase("swifdua3cvtp");
print "External Payment Phase: $external_payment_phase->id\n";
} catch (Recurly_ValidationError $e) {
print "Validation error: $e";
} catch (Recurly_Error $e) {
// Could not find external payment phase
print "Bad request: $e";
}
- lang: Ruby
source: |-
external_subscription = Recurly::ExternalSubscription.find('pbux7jvmauhe')
external_payment_phase = external_subscription.get_external_payment_phase('swifdua3cvtp')
- lang: Python
source: |-
external_subscription = recurly.ExternalSubscription.get("pbux7jvmauhe")
external_payment_phase = external_subscription.get_external_payment_phase("swifdua3cvtp")
- lang: Dotnet
source: |-
var externalSubscription = ExternalSubscription.Get("pbux7jvmauhe");
var externalPaymentPhase = externalSubscription.GetExternalPaymentPhase("swifdua3cvtp");
"/external_payment_phases/{external_payment_phase_id}":
parameters:
- "$ref": "#/components/parameters/external_payment_phase_id"
get:
tags:
- external-payment-phases
operationId: getExternalPaymentPhase
summary: Fetch an external payment phase
responses:
"200":
description: Details for an external payment phase.
content:
application/xml:
schema:
"$ref": "#/components/schemas/ExternalPaymentPhase"
example: >-
tws7x821sv1z2023-11-08T21:02:39Z2023-12-06T21:02:39Z141TWO_MONTHS0.0USD2022-10-10T21:40:57Z2022-10-10T21:40:57Z
"404":
description: Incorrect site or external payment phase ID.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
example: >-
not_foundCouldn't find ExternalPaymentPhase with id
default:
description: Unexpected error.
content:
application/xml:
schema:
"$ref": "#/components/schemas/Error"
x-codeSamples:
- lang: PHP
source: |-
-
su3n18oalr9mlegacy_usaLegacy USA94250 Sadye RampApt. 771OaklandCA94605US718-555-123494250 Sadye RampApt. 771OaklandCA94605US718-555-1234GBCO123456782023-05-04T17:45:43Z2023-05-04T17:45:43Z8djclk3992ikv8737kc9l
schema:
type: array
items:
$ref: "#/components/schemas/BusinessEntity"
x-codeSamples:
- lang: PHP
source: |-
-
su3n18oalr9mlegacy_usaLegacy USA94250 Sadye RampApt. 771OaklandCA94605US718-555-123494250 Sadye RampApt. 771OaklandCA94605US718-555-1234GBCO123456782023-05-04T17:45:43Z2023-05-04T17:45:43Z8djclk3992ikv8737kc9l
schema:
$ref: "#/components/schemas/BusinessEntity"
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find BusinessEntity with uuid = xxx
x-codeSamples:
- lang: PHP
source: |-
-
Lon Doner221B Baker St.LondonW1K 6AHGB421f7b7d414e4c6792938e7c49d552e9paid1005200002018-01-30T21:11:50Z0chargepurchase200001200EUR2020424USD2016-06-25T12:00:00ZusstCA00netautomatictrue
"404":
description: ""
content:
application/xml:
example: >-
not_foundCouldn't find BusinessEntity with uuid = xxx
x-codeSamples:
- lang: PHP
source: |-
500400
xml:
name: currrencies
CurrencyCode:
type: string
maxLength: 3
description: 3-letter ISO 4217 currency code.
example: USD
xml:
name: currency
CustomerNotes:
type: string
default: ""
description: Optional notes field. This will default to the Customer
Notes text specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Customer Notes. Custom notes will stay with a subscription
on all renewals. Custom notes made on an invoice for a one time
charge will not carry over to subsequent invoices.
xml:
name: customer_notes
CustomField:
type: object
required:
- name
- value
properties:
name:
type: string
maxLength: 50
pattern: "/^[a-z0-9_-]+$/i"
title: Field name
description: Fields must be created in the UI before values can be assigned to them.
value:
type: string
maxLength: 255
title: Field value
description: Any values that resemble a credit card number or security code (CVV/CVC) will be rejected.
CustomFieldDefinition:
type: object
title: Custom field definition
properties:
id:
type: string
title: Custom field definition ID
readOnly: true
object:
type: string
title: Object type
readOnly: true
related_type:
title: Related Recurly object type
"$ref": "#/components/schemas/RelatedTypeEnum"
name:
type: string
title: Name
description:
Used by the API to identify the field or reading and writing.
The name can only be used once per Recurly object type.
pattern: "/^[a-z0-9_-]+$/i"
maxLength: 50
user_access:
title: User access
description: |
The access control applied inside Recurly's admin UI:
- `api_only` - No one will be able to view or edit this field's data via the admin UI.
- `read_only` - Users with the Customers role will be able to view this field's data via the admin UI, but
editing will only be available via the API.
- `write` - Users with the Customers role will be able to view and edit this field's data via the admin UI.
- `set_only` - Users with the Customers role will be able to set this field's data via the admin console.
"$ref": "#/components/schemas/UserAccessEnum"
display_name:
type: string
title: Display name
description:
Used to label the field when viewing and editing the field
in Recurly's admin UI.
maxLength: 50
tooltip:
type: string
title: Tooltip description
description:
Displayed as a tooltip when editing the field in the Recurly
admin UI.
pattern: "/^[a-z0-9_-]+$/i"
maxLength: 255
created_at:
type: string
format: date-time
title: Created at
readOnly: true
updated_at:
type: string
format: date-time
title: Last updated at
readOnly: true
deleted_at:
type: string
format: date-time
title: Deleted at
description:
Definitions are initially soft deleted, and once all the values
are removed from the accouts or subscriptions, will be hard deleted an
no longer visible.
readOnly: true
CustomFieldDefinitionList:
type: object
properties:
object:
type: string
title: Object type
description: Will always be List.
has_more:
type: boolean
description: Indicates there are more results on subsequent pages.
next:
type: string
description: Path to subsequent page of results.
data:
type: array
items:
"$ref": "#/components/schemas/CustomFieldDefinition"
CustomFields:
type: array
items:
$ref: "#/components/schemas/CustomField"
title: Custom Fields
description: The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.
DestinationTaxAddressSourceEnum:
type: string
title: Destination tax address source
description:
The source of the address that will be used as the destinaion in determining taxes.
Available only when the site is on an Elite plan.
A value of "destination" refers to the "Customer tax address".
A value of "origin" refers to the "Business entity tax address".
default: destination
enum:
- destination
- origin
Email:
type: string
maxLength: 255
example: verena@example.com
xml:
name: email
ErrorTypeEnum:
type: string
enum:
- bad_request
- immutable_subscription
- internal_server_error
- invalid_api_key
- invalid_api_version
- invalid_content_type
- invalid_permissions
- invalid_token
- missing_feature
- not_found
- rate_limited
- service_not_available
- simultaneous_request
- tax_service_error
- transaction
- unauthorized
- unavailable_in_api_version
- unknown_api_version
- validation
FirstName:
type: string
title: First name
example: Verena
xml:
name: first_name
GeneralLedgerAccountTypeEnum:
type: string
enum:
- liability
- revenue
xml:
name: account_type
GeneralLedgerAccountId:
type: string
title: General Ledger Account ID
description: |
The ID of a general ledger account. General ledger accounts are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.
maxLength: 13
example: iiznlrvdt8py
xml:
name: id
GeneralLedgerAccountCode:
type: string
title: Accounting code for the ledger account.
description: |
Unique code to identify the ledger account. Each code must start
with a letter or number. The following special characters are
allowed: `-_.,:`
pattern: "/^[A-Za-z0-9](( *)?[\\-A-Za-z0-9_.,:])*$/"
example: 100abc
maxLength: 255
xml:
name: code
GeneralLedgerAccountDescription:
type: string
title: Description
description: Optional description.
example: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
maxLength: 255
xml:
name: description
ImportedTrial:
type: boolean
description:
Indicates if the subscription is to be treated as an import for
data analysis or a real trial. This value can only be
changed on a trial subscription and is persisted for its
lifetime.
default: false
Item:
type: object
description: Full item details.
properties:
item_code:
type: string
default: ""
description: Unique code to identify the item. Max of 50 characters.
name:
type: string
default: ""
description: Item name. Max of 255 characters.
description:
type: string
default: ""
description: Optional plan description, not displayed.
external_sku:
type: string
default: ""
description:
Stock keeping unit to link the item to other inventory. Max of 50
characters.
accounting_code:
type: string
default: ""
description:
"Accounting code for invoice line items. Code may only contain the
following characters: [a-z 0-9 @ - _ .]. Max of 20
characters."
revenue_schedule_type:
type: string
default: evenly
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Item should be recognized.
enum:
- never
- evenly
- at_range_start
- at_range_end
tax_exempt:
type: boolean
default: "false"
description:
"`true` exempts tax on the charge, `false` applies tax on the
charge. If not defined, defaults to `false`."
state:
type: string
default: ""
description:
The current state of the item. Will be either active or inactive.
Read-only.
enum:
- active
- inactive
custom_fields:
$ref: "#/components/schemas/CustomFields"
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
created_at:
type: string
format: date-time
description: The datetime this item was created
updated_at:
type: string
format: date-time
description: The datetime this item was last updated
LastName:
type: string
title: Last name
example: Example
xml:
name: last_name
NetTerms:
type: integer
title: Net terms
description: |-
Integer paired with `Net Terms Type` and representing the number
of days past the current date (for `net` Net Terms Type) or days after
the last day of the current month (for `eom` Net Terms Type) that the
invoice will become past due. For `manual` collection method, an additional 24 hours is
added to ensure the customer has the entire last day to make payment before
becoming past due. For example:
If an invoice is due `net 0`, it is due 'On Receipt' and will become past due 24 hours after it's created.
If an invoice is due `net 30`, it will become past due at 31 days exactly.
If an invoice is due `eom 30`, it will become past due 31 days from the last day of the current month.
For `automatic` collection method, the additional 24 hours is not added. For example, On-Receipt is due immediately, and `net 30` will become due exactly 30 days from invoice generation, at which point Recurly will attempt collection.
When `eom` Net Terms Type is passed, the value for `Net Terms` is restricted to `0, 15, 30, 45, 60, or 90`.
For more information on how net terms work with `manual` collection visit our docs page (https://docs.recurly.com/docs/manual-payments#section-collection-terms)
or visit (https://docs.recurly.com/docs/automatic-invoicing-terms#section-collection-terms) for information about net terms using `automatic` collection.
minimum: 0
default: 0
NetTermsTypeEnum:
type: string
title: Net Terms Type
description: |
Optionally supplied string that may be either `net` or `eom` (end-of-month).
When `net`, an invoice becomes past due the specified number of `Net Terms` days from the current date.
When `eom` an invoice becomes past due the specified number of `Net Terms` days from the last day of the current month.
enum:
- net
- eom
default: net
OriginTaxAddressSourceEnum:
type: string
title: Origin tax address source
description:
The source of the address that will be used as the origin in determining taxes.
Available only when the site is on an Elite plan.
A value of "origin" refers to the "Business entity tax address".
A value of "destination" refers to the "Customer tax address".
default: origin
enum:
- origin
- destination
PercentageTiersArray:
type: array
title: Percentage Tiers
items:
$ref: "#/components/schemas/PercentageTierObject"
PercentageTierCollection:
type: object
title: Percentage Tier
required:
- currency
- tiers
properties:
currency:
type: string
title: currency
tiers:
$ref: "#/components/schemas/PercentageTiersArray"
PercentageTierObject:
type: object
title: Tier
required:
- ending_amount_in_cents
- usage_percentage
properties:
ending_amount_in_cents:
type: integer
title: Ending amount in cents
usage_percentage:
$ref: "#/components/schemas/TierUsagePercentage"
PlanPercentageTiers:
type: array
description: |
Required if `tier_type != "flat"` and `usage_type == "percentage"`.
Array of objects which must have at least one set of tiers
per currency and the currency code. The tier_type must be `volume` or `tiered`,
if not, it must be absent. There must be one tier without an `ending_amount_in_cents` value
which represents the final tier.
items:
$ref: "#/components/schemas/PercentageTierCollection"
PerformanceObligationId:
type: string
title: Performance Obligation ID
description: |
The ID of a performance obligation. Performance obligations are
only accessible as a part of the Recurly RevRec Standard and
Recurly RevRec Advanced features.
maxLength: 13
xml:
name: id
PlanCode:
type: string
default: ""
maxLength: 50
description:
"Unique code to identify the plan. This code may only contain the
following characters: [a-z 0-9 @ - _ .]. Max of 50
characters."
example: gold
PricingModelTypeEnum:
type: string
title: Pricing Model
enum:
- fixed
- ramp
default: fixed
description: |
A fixed pricing model has the same price (i.e. `unit_amount_in_cents`)
for each billing period. A ramp pricing model instead defines a set of
ramp intervals (i.e. `ramp_intervals`), where a subscription changes
price on a specified cadence of billing periods. The price change could
be an increase or decrease. Ramp pricing is only available on Recurly
Pro and Elite plans, as well as sandbox sites.
xml:
name: pricing_model
ProrationSettings:
type: object
title: Proration Settings
description:
Allows you to control how any resulting charges and credits will
be calculated and prorated.
properties:
charge:
"$ref": "#/components/schemas/ProrationSettingsChargeEnum"
credit:
"$ref": "#/components/schemas/ProrationSettingsCreditEnum"
ProrationSettingsChargeEnum:
type: string
title: Charge
description: Determines how the amount charged is determined for this change
default: prorated_amount
enum:
- full_amount
- prorated_amount
- none
ProrationSettingsCreditEnum:
type: string
title: Credit
description: Determines how the amount credited is determined for this change
default: prorated_amount
enum:
- full_amount
- prorated_amount
- none
PutMethodAttribute:
type: string
enum:
- put
xml:
attribute: true
Quantity:
type: integer
description: Optionally override the default quantity of 1.
default: 1
minimum: 0
xml:
name: quantity
RampIntervalStartingBillingCycle:
type: integer
description: Represents the billing cycle where a ramp interval starts.
minimum: 1
default: 1
ReferenceHref:
type: string
format: url
example: "https://your-subdomain.recurly.com/v2/..."
xml:
attribute: true
RelatedTypeEnum:
type: string
enum:
- account
- item
- plan
- subscription
- charge
RenewalBillingCycles:
type: integer
description: The number of billing periods in the subscription's next
term. Will default to the plan's `total_billing_cycles` unless
specified.
minimum: 0
xml:
name: renewal_billing_cycles
RevenueScheduleTypeEnum:
type: string
description: Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Subscription should
be recognized. When creating a Subscription, available
schedule types are `never`, `evenly`, `at_range_start`, or
`at_range_end`. If no `revenue_schedule_type` is set, the
Subscription will inherit the `revenue_schedule_type` from
its Plan.
enum:
- never
- evenly
- at_range_start
- at_range_end
xml:
name: revenue_schedule_type
ShippingAddressId:
type: integer
format: int64
default: ""
description:
All subscriptions and adjustments on the purchase will use this
shipping address unless they specify one of their own. Any
subscriptions for which this address might apply will also
use it in future renewals unless changed or removed. Cannot
be used if a new shipping address is created at the account
level.
xml:
name: "shipping_address_id"
ShippingMethod:
type: object
properties:
object:
type: string
title: Object type
readOnly: true
code:
type: string
title: Code
description: The internal name used identify the shipping method.
maxLength: 50
name:
type: string
title: Name
description: The name of the shipping method displayed to customers.
maxLength: 100
accounting_code:
type: string
title: Accounting Code
description: Accounting code for shipping method.
maxLength: 20
tax_code:
type: string
title: Tax code
description: |
Used by Avalara, Vertex, and Recurly’s built-in tax feature. The tax
code values are specific to each tax system. If you are using Recurly’s
built-in taxes the values are:
- `FR` – Common Carrier FOB Destination
- `FR022000` – Common Carrier FOB Origin
- `FR020400` – Non Common Carrier FOB Destination
- `FR020500` – Non Common Carrier FOB Origin
- `FR010100` – Delivery by Company Vehicle Before Passage of Title
- `FR010200` – Delivery by Company Vehicle After Passage of Title
- `NT` – Non-Taxable
maxLength: 50
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
created_at:
type: string
format: date-time
title: Created at
readOnly: true
updated_at:
type: string
format: date-time
title: Last updated at
readOnly: true
StartsAt:
type: string
format: date-time
default: ""
description: If set, the subscription will begin on this specified
date. The subscription will apply the setup fee and trial period,
unless the plan has no trial. Omit this field if the subscription
should be started immediately.
SubscriptionAddOns:
type: array
description: Nested add-on information for the subscription. When
creating, the new subscription will have no add-ons unless specified.
items:
type: object
default: []
xml:
name: subscription_add_ons
wrapped: true
SubscriptionStateEnum:
type: string
enum:
- active
- canceled
- expired
- failed
- future
- paused
SubscriptionPercentageTiers:
type: array
description: |
Required if `tier_type != "flat"` and `usage_type == "percentage"`.
Array of objects which must have at least one set of tiers.
The tier_type must be `volume` or `tiered`,
if not, it must be absent. There must be one tier without an `ending_amount_in_cents` value
which represents the final tier.
items:
$ref: "#/components/schemas/SubscriptionPercentageTier"
SubscriptionPercentageTier:
type: object
title: Percentage Tier
required:
- ending_amount_in_cents
- usage_percentage
properties:
ending_amount_in_cents:
type: integer
title: Ending amount in cents
usage_percentage:
$ref: "#/components/schemas/TierUsagePercentage"
TaxInclusive:
type: boolean
description: Determines whether or not tax is included in the unit amount.
The Tax Inclusive Pricing feature (separate from the Mixed Tax Pricing
feature) must be enabled to use this flag.
default: false
xml:
name: tax_inclusive
TermsAndConditions:
type: string
default: ""
description:
Optional notes field. This will default to the Terms and Conditions
text specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Terms and Conditions. Custom notes will stay with a
subscription on all renewals.
xml:
name: terms_and_conditions
Tier:
type: object
title: Tier
required:
- ending_quantity
- unit_amount_in_cents
properties:
ending_quantity:
type: integer
title: Ending quantity
description: Upper limit for the tier.
unit_amount_in_cents:
type: integer
title: Unit amount in cents
description: Monetary amount to charge for a tier.
TierUsagePercentage:
type: string
pattern: ^(100(\.0{1,4})?|\d{1,2}(\.\d{1,4})?)$
description:
The percentage taken of the monetary amount of usage tracked. This
can be up to 4 decimal places. A value between 0.0000 and 100.0.
Tiers:
type: array
title: Tiers
description:
If the `tier_type` is `flat`, then `tiers` must be absent. The
`tiers` object must include one to many tiers with
`ending_quantity` and `unit_amount_in_cents` for the desired
currencies. There must be one tier with an `ending_quantity`
of 999999999 which is the default if not provided.
items:
$ref: "#/components/schemas/Tier"
TotalBillingCycles:
type: integer
minimum: 0
description: The total number of billing cycles for the current
subscription term.
xml:
name: total_billing_cycles
TrialEndsAt:
type: string
format: date-time
default: ""
description:
If set, overrides the default trial behavior for the subscription.
This must be a date and time, preferably in UTC. If the date
is in the past, the subscription will skip the trial.
xml:
name: trial_ends_at
UserAccessEnum:
type: string
enum:
- api_only
- read_only
- write
- set_only
VatReverseChargeNotes:
type: string
default: ""
description: VAT Reverse Charge Notes only appear if you have EU VAT
enabled or are using your own Avalara AvaTax account and the customer
is in the EU, has a VAT number, and is in a different
country than your own. This will default to the VAT Reverse
Charge Notes text specified on the Tax Settings page in your
Recurly admin, unless custom notes were created with the
original subscription. Specify custom notes with this tag to
add or override VAT Reverse Charge Notes. Custom notes will
stay with a subscription on all renewals.
xml:
name: vat_reverse_charge_notes
### "molecules" (collections of atoms as arrays/objects)
# submodels and full models are defined here as combinations of atoms
# and other molecules. be sure to test any clever schemas in the final
# redoc rendering as sometimes they display with undesired names.
Account:
allOf:
- $ref: "#/components/schemas/AccountMini"
- properties:
parent_account:
type: string
description: The URL of the parent for the specified account.
child_accounts:
type: string
description: The URL of the child accounts for the specified account.
bill_to:
type: string
description:
"`self` or `parent`. Determines whether all charges are billed
using parent's billing information or the account itself. If
bill_to = parent, all invoices resulting in charges and credits
originating from a child will be created on the parent account. (e.g
creating a subscription on the child account will be billed to
parent and invoiced on the parent account)"
adjustments:
type: string
description: The URL of adjustments for the specified account.
account_balance:
type: string
description: The URL of the account balance for the specified account.
billing_info:
type: string
description: The URL of billing info for the specified account.
invoices:
type: string
description: The URL of invoices for the specified account.
redemption:
type: string
description: The URL of the coupon redemption for the specified account.
subscriptions:
type: string
description: The URL of subscriptions for the specified account.
transactions:
type: string
description: The URL of transactions for the specified account.
notes:
type: string
description: The URL of notes on the account
state:
type: string
description: "The state of accounts to return: `active` or `closed`."
username:
type: string
description: The username of the account.
cc_emails:
type: string
description: Additional email address that should receive account
correspondence. These should be separated only by commas. These CC
emails will receive all emails that the `email` field also receives.
company_name:
type: string
description: The company name of the account.
vat_number:
type: string
description: The VAT number of the account (to avoid having the VAT applied).
tax_exempt:
type: boolean
description:
The tax status of the account. `true` exempts tax on the account,
`false` applies tax on the account.
address:
type: object
description:
"The nested address information of the account: `address1`,
`address2`, `city`, `state`, `zip`, `country`, `phone`."
shipping_address:
type: object
description:
"The nested shipping address information of the account:
`first_name`, `last_name`, `company_name`, `email`, `phone`,
`vat_number`, `address1`, `address2`, `city`, `state`, `zip`,
`country`, `nickname`. You can pass in up to 20 account shipping
addresses along with the request to create a new account. When
providing a shipping address, the following are required:
first_name, last_name, address1, city, state, zip, and country."
accept_language:
type: string
description:
The ISO 639-1 language code from the user's browser, indicating
their preferred language and locale. This attribute is different
from `preferred_locale` and does not determine which language emails
sent on behalf of the merchant.
hosted_login_token:
type: string
description:
"The unique token for automatically logging the account in to the
hosted management pages. You may automatically log the user into
their hosted management pages by directing the user to:
`https://:subdomain.recurly.com/account/:hosted_login_token`."
created_at:
type: string
format: date-time
description: The date and time the account was created in Recurly.
updated_at:
type: string
format: date-time
description: The date and time the account or its billing info was last updated.
closed_at:
type: string
format: date-time
description: For closed accounts, the date and time it was closed.
has_live_subscription:
type: boolean
description: True if the account has at least one live subscription.
has_active_subscription:
type: boolean
description: True if the account has at least one active subscription.
has_future_subscription:
type: boolean
description: True if the account has at least one future subscription.
has_canceled_subscription:
type: boolean
description: True if the account has at least one canceled subscription.
has_paused_subscription:
type: string
description: True if the account has at least one paused subscription.
has_past_due_invoice:
type: boolean
description: True if the account has at least one past due invoice.
preferred_locale:
type: string
description:
Used to determine the language and locale of emails sent on behalf
of the merchant to the customer. The list of locales is restricted
to those the merchant has enabled on the site.
preferred_time_zone:
type: string
description:
The [IANA time zone name](https://docs.recurly.com/docs/email-time-zones-and-time-stamps#supported-api-iana-time-zone-names) used to determine the time zone of emails sent
on behalf of the merchant to the customer.
dunning_campaign_id:
type: string
description: The uuid of the associated dunning campaign of the account.
override_business_entity_id:
type: string
description:
The uuid of the associated business entity of the account.
Available when the `Multiple Business Entities` feature is enabled.
custom_fields:
$ref: "#/components/schemas/CustomFields"
AccountWithCodeOnly:
type: object
title: Account
required:
- account_code
properties:
account_code:
$ref: "#/components/schemas/AccountCode"
xml:
name: account
AccountMini:
allOf:
- $ref: "#/components/schemas/AccountWithCodeOnly"
- properties:
first_name:
allOf:
- $ref: "#/components/schemas/FirstName"
- description: The first name of the account.
last_name:
allOf:
- $ref: "#/components/schemas/LastName"
- description: The last name of the account.
email:
allOf:
- $ref: "#/components/schemas/Email"
- description: The email address of the account.
Address:
type: object
properties:
address1:
type: string
example: 123 Main St.
address2:
type: string
example: Suite 101
city:
type: string
example: San Francisco
state:
type: string
example: CA
zip:
type: string
example: 94105
country:
type: string
example: US
maxLength: 2
phone:
type: string
example: 555-222-1212
AddressWithName:
allOf:
- $ref: "#/components/schemas/Address"
- properties:
first_name:
$ref: "#/components/schemas/FirstName"
last_name:
$ref: "#/components/schemas/LastName"
AddressWithNameResponse:
allOf:
- $ref: "#/components/schemas/Address"
- properties:
name:
type: string
description: Full name comprised of `first_name` and `last_name`.
example: Verena Example
AddOn:
type: object
properties:
plan_code:
type: string
description: Unique code to identify the plan.
plan:
type: string
description: The URL of the plan the add-on is in.
measured_unit:
type: string
description:
If the add-on is usage-based, this is the URL of the measured unit
associated with the add-on.
add_on_code:
type: string
description: The add-on code. Max of 50 characters.
item_code:
type: string
description:
Item code for an existing active item to be used as an add-on on
the plan. This will be unique identifier for add-on within the plan.
name:
type: string
description: The add-on name. Max of 255 characters.
default_quantity:
type: integer
description: Default quantity for the hosted pages, defaults to 1.
display_quantity_on_hosted_page:
type: boolean
description:
If true, displays a quantity field on the hosted pages for the
add-on.
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax
solution to determine taxation rules. You can pass in specific tax codes using any of
these tax integrations. For Recurly's In-the-Box tax offering you can also choose to
instead use simple values of `unknown`, `physical`, or `digital` tax codes. If
`item_code`/`item_id` is part of the request then `tax_code` must be absent.
unit_amount_in_cents:
type: array
items:
type: object
description:
Array of unit amounts with their currency code. Max 10000000. Ex.
$5.00 USD would be 500. `unit_amount_in_cents` is not
allowed when creating or updating a tiered add-on.
accounting_code:
type: string
description:
Accounting code for invoice line items for the add-on. Max of 20
characters.
add_on_type:
type: string
description:
Whether the add-on type is Fixed (fixed), or Usage-Based (usage).
If `item_code` is present, `add_on_type` must be absent.
optional:
type: boolean
description:
Whether the add-on is optional for the customer to include in their
purchase on the hosted payment page. If false, the add-on will be
included when a subscription is created through the Recurly UI.
However, the add-on will not be included when a subscription is
created through the API. See
https://dev.recurly.com/docs/subscription-add-ons for how to create
a subscription with add-ons using the API.
usage_type:
type: string
description:
If `add_on_type` = `usage`, you will see `usage_type`, which can be
`price` or `percentage`. If `price`, the price is defined in
`unit_amount_in_cents`. If `percentage`, the percentage is defined
in `usage_percentage`.
usage_calculation_type:
type: string
description:
The method used to calculate usage for a billing period. Can be null,
`cumulative`, or `last_in_period`. If no value is specified, behavior will default
to cumulative billing. For cumulative billing, all usage records for the billing
period will be summed together. For last-in-period billing, only the last recorded
usage record in the billing period will be used.
usage_percentage:
$ref: "#/components/schemas/UsagePercentage"
revenue_schedule_type:
type: string
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Plan should be recognized.
When creating a Plan, if you supply an `end_date` and `end_date`
available schedule types are `never`, `evenly`, `at_range_start`, or
`at_range_end`.
created_at:
type: string
format: date-time
description: When the add-on was created in the plan.
updated_at:
type: string
format: date-time
description: When the add-on was last updated.
tier_type:
type: string
description:
Add-on tier type. Defaults to flat which charges a fixed price per
unit. When tiered-pricing is used, tier_type can be tiered, volume
or stairstep. For more info, see our product docs
(https://docs.recurly.com/docs/billing-models#section-quantity-based).
This value cannot be changed after it has been saved.
tiers:
$ref: "#/components/schemas/Tiers"
percentage_tiers:
$ref: "#/components/schemas/PlanPercentageTiers"
required:
- plan_code
AdjustmentBase:
type: object
properties:
account:
type: string
description: The URL of the account for the specified adjustment.
invoice:
type: string
description: The URL of the invoice for the specified adjustment.
uuid:
type: string
description: The unique identifier of the adjustment.
state:
type: string
description: "The state of the adjustments to return: `pending` or `invoiced`."
description:
type: string
description: Description of the adjustment for the adjustment. Max 255 characters.
accounting_code:
type: string
description: Accounting code. Max of 20 characters.
origin:
type: string
description:
"The origin of the adjustment to return: `plan`, `plan_trial`,
`setup_fee`, `add_on`, `add_on_trial`, `one_time`, `debit`,
`credit`, `coupon`, or `carryforward`."
vertex_transaction_type:
"$ref": "#/components/schemas/VertexTransactionTypeEnum"
unit_amount_in_cents:
type: integer
description:
Positive amount for a charge, negative amount for a credit. Max
10000000.
quantity:
type: string
description: Quantity.
quantity_decimal:
type: string
title: Quantity Decimal
description:
A floating-point alternative to Quantity. If this value is
present, it will be used in place of Quantity for calculations, and Quantity
will be the rounded integer value of this number. This field supports
up to 9 decimal places. The Decimal Quantity feature must be enabled to
utilize this field.
original_adjustment_uuid:
type: string
description: Only shows if adjustment is a credit created from another credit.
discount_in_cents:
type: integer
description: The discount on the adjustment, in cents.
tax_in_cents:
type: integer
description: The tax on the adjustment, in cents.
total_in_cents:
type: integer
description: The total amount of the adjustment, in cents.
currency:
type: string
description: Currency, 3-letter ISO code.
taxable:
type: boolean
description: "`true` if the current adjustment is taxable, `false` if it is not."
tax_type:
type: string
description: The tax type of the adjustment.
tax_region:
type: string
description: The tax region of the adjustment.
tax_rate:
type: string
description: The tax rate of the adjustment.
origin_tax_address_source:
"$ref": "#/components/schemas/OriginTaxAddressSourceEnum"
destination_tax_address_source:
"$ref": "#/components/schemas/DestinationTaxAddressSourceEnum"
tax_exempt:
type: boolean
description:
"`true` exempts tax on the charge, `false` applies tax on the
charge. If not defined, then defaults to the Plan and Site settings.
This attribute does not work for credits (negative adjustments).
Credits are always post-tax. Pre-tax discounts should use the
Coupons feature."
tax_details:
type: array
items:
type: object
description:
"The nested address information of the adjustment: `name `, `type`,
`tax_rate`, `tax_in_cents`."
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax
solution to determine taxation rules. You can pass in specific tax codes using any of
these tax integrations. For Recurly's In-the-Box tax offering you can also choose to
instead use simple values of `unknown`, `physical`, or `digital` tax codes.
start_date:
type: string
format: date-time
description: A timestamp associated with when the adjustment began.
end_date:
type: string
format: date-time
description: A timestamp associated with when the adjustment ended.
created_at:
type: string
format: date-time
description: A timestamp associated with when the adjustment was created.
product_code:
type: string
description:
For plan related line items this will be the plan's code, for
add-on related line items it will be the add-on's code.
subscription:
type: string
description:
A link to the adjustment's invoice's first subscription (if it
exists).
proration_rate:
type: number
format: float
description:
The proration rate is only present on prorated adjustments. It
represents how much the adjustment was prorated to account for a mid
cycle subscription change.
credit_reason_code:
type: string
description:
Can be set on POST if adjustment is a credit (unit_amount_in_cents
< 0)
shipping_address:
type: object
description: The shipping address for this adjustment.
item:
type: string
description:
If there is an item associated with the adjustment, a link to the
resource will be included in the response.
item_code:
type: string
description:
The `item_code` for the item associated with the adjustment, if
there is one. Associates the adjustment with an item and sets
related attributes on the adjustment from the default values on the
item. ``, ``, ``,
`` and `` are not accepted when ``
is present.
external_sku:
type: string
description:
The `external_sku` for the item associated with the adjustment, if
there is one.
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
custom_fields:
"$ref": "#/components/schemas/CustomFields"
AdjustmentCreate:
allOf:
- $ref: "#/components/schemas/AdjustmentBase"
- type: object
properties:
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
xml:
name: adjustment
Adjustment:
allOf:
- $ref: "#/components/schemas/AdjustmentBase"
- type: object
properties:
type:
type: string
description: "The type of adjustment to return: `charge` or `credit`."
liability_gl_account_code:
"$ref": "#/components/schemas/GeneralLedgerAccountCode"
revenue_gl_account_code:
"$ref": "#/components/schemas/GeneralLedgerAccountCode"
BillingInfoCC:
type: object
properties:
number:
type: string
example: 4111-1111-1111-1111
month:
type: string
example: 12
year:
type: string
example: 2038
xml:
name: billing_info
BusinessEntity:
type: object
description: Business entity details
properties:
id:
title: Business entity ID
type: string
maxLength: 13
readOnly: true
code:
title: Business entity code
type: string
maxLength: 50
description: The entity code of the business entity.
name:
type: string
title: Name
description:
This name describes your business entity and will appear on
the invoice.
maxLength: 255
invoice_display_address:
title: Invoice display address
description:
Address information for the business entity that will appear
on the invoice.
"$ref": "#/components/schemas/Address"
tax_address:
title: Tax address
description:
Address information for the business entity that will be used
for calculating taxes.
"$ref": "#/components/schemas/Address"
origin_tax_address_source:
"$ref": "#/components/schemas/OriginTaxAddressSourceEnum"
destination_tax_address_source:
"$ref": "#/components/schemas/DestinationTaxAddressSourceEnum"
subscriber_location_countries:
type: array
title: Subscriber location countries
description: List of countries for which the business entity will be used.
items:
type: object
default_vat_number:
type: string
title: Default VAT number
description: VAT number for the customer used on the invoice.
maxLength: 20
default_registration_number:
type: string
title: Default registration number
description: Registration number for the customer used on the invoice.
maxLength: 30
created_at:
type: string
format: date-time
title: Created at
readOnly: true
updated_at:
type: string
format: date-time
title: Last updated at
readOnly: true
default_liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
default_revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
CouponCodes:
type: array
description: Provide this elements if you want to redeem multiple coupons.
You must have Multiple Coupons Per Account enabled in Coupon Settings in
order to redeem multiple coupons.
items:
properties:
coupon_code:
$ref: "#/components/schemas/CouponCode"
xml:
name: coupon_codes
CreditPayment:
type: object
properties:
account:
type: string
description: The URL of the account for the credit payment.
uuid:
type: string
description: The unique identifier of the credit payment.
action:
type: string
description:
"The action the credit payment was created for. Is also a query
param on the main list. Allowed Values: [payment, gift_card, refund,
reduction, write_off]."
currency:
type: string
description: Currency, 3-letter ISO code.
amount_in_cents:
type: integer
description: Amount of the credit payment.
original_invoice:
type: string
description: The URL of the original invoice for the credit payment.
applied_to_invoice:
type: string
description: The URL of the invoice on which this payment was applied.
original_credit_payment:
type: string
description:
The reference of the original credit payment being refunded. Only
shown if action = 'refund'.
refund_transaction:
type: string
description:
The reference of the refund transaction that matches the refund
credit payment. Only shown if action = 'refund'.
created_at:
type: string
format: date-time
description: When the credit payment was created.
updated_at:
type: string
format: date-time
description:
When the credit payment was created or updated. Will only update if
voided.
voided_at:
type: string
format: date-time
description:
When the credit payment was voided. Will only be voided if the
credit payment was on a charge invoice that was then failed.
DunningCampaign:
type: object
properties:
id:
type: string
code:
type: string
description: Campaign code.
name:
type: string
description: Campaign name.
description:
type: string
description: Campaign description.
default_campaign:
type: boolean
description:
Whether or not this is the default campaign for accounts or
plans without an assigned dunning campaign.
dunning_cycles:
type: array
description: Dunning Cycle settings.
items:
"$ref": "#/components/schemas/DunningCycle"
created_at:
type: string
format: date-time
description: When the current campaign was created in Recurly.
updated_at:
type: string
format: date-time
description: When the current campaign was updated in Recurly.
deleted_at:
type: string
format: date-time
description: When the current campaign was deleted in Recurly.
DunningCycle:
type: object
properties:
type:
enum:
- automatic
applies_to_manual_trial:
type: boolean
description:
Whether the dunning settings will be applied to manual trials.
Only applies to trial cycles.
first_communication_interval:
type: integer
description:
The number of days after a transaction failure before the first
dunning email is sent.
send_immediately_on_hard_decline:
type: boolean
description:
Whether or not to send an extra email immediately to customers
whose initial payment attempt fails with either a hard decline or invalid
billing info.
intervals:
type: array
description: Dunning intervals.
items:
"$ref": "#/components/schemas/DunningInterval"
expire_subscription:
type: boolean
description:
Whether the subscription(s) should be cancelled at the end
of the dunning cycle.
fail_invoice:
type: boolean
description:
Whether the invoice should be failed at the end of the dunning
cycle.
total_dunning_days:
type: integer
description:
The number of days between the first dunning email being sent
and the end of the dunning cycle.
total_recycling_days:
type: integer
description:
The number of days between a transaction failure and the end
of the dunning cycle.
version:
type: integer
description: Current campaign version.
created_at:
type: string
format: date-time
description: When the current settings were created in Recurly.
updated_at:
type: string
format: date-time
description: When the current settings were updated in Recurly.
DunningInterval:
properties:
days:
type: integer
description: Number of days before sending the next email.
email_template:
type: string
description: Email template being used.
Entitlement:
type: object
properties:
object:
type: string
description: Entitlement
customer_permission:
"$ref": "#/components/schemas/CustomerPermission"
granted_by:
type: array
description: Subscription or item that granted the customer permission.
items:
"$ref": "#/components/schemas/GrantedBy"
created_at:
type: string
format: date-time
description: Time object was created.
updated_at:
type: string
format: date-time
description: Time the object was last updated
Entitlements:
type: object
description:
A list of privileges granted to a customer through the purchase
of a plan or item.
properties:
object:
type: string
title: Object Type
has_more:
type: boolean
description: Indicates there are more results on subsequent pages.
next:
type: string
description: Path to subsequent page of results.
data:
type: array
items:
"$ref": "#/components/schemas/Entitlement"
CustomerPermission:
type: object
properties:
id:
type: string
description: Customer permission ID.
code:
type: string
description: Customer permission code.
name:
type: string
description: Customer permission name.
description:
type: string
description: Description of customer permission.
object:
type: string
description: It will always be "customer_permission".
GrantedBy:
type: object
description:
The subscription or external subscription that grants customer
permissions.
properties:
object:
type: string
title: Object Type
id:
type: string
description:
The ID of the subscription or external subscription that grants
the permission to the account.
ExternalProductReference:
type: object
properties:
id:
type: string
description: System-generated unique identifier for an external product reference.
reference_code:
type: string
description:
A code which associates the external product to a corresponding object or resource in an
external platform like the Apple App Store or Google Play Store.
external_connection_type:
type: string
description: Source connection platform.
created_at:
type: string
format: date-time
description: When the external product reference was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external product reference was updated in Recurly.
ExternalProduct:
type: object
properties:
id:
type: string
description: System-generated unique identifier for an external product.
name:
type: string
description: Name to identify the external product in Recurly.
plan:
$ref: "#/components/schemas/PlanMini"
created_at:
type: string
format: date-time
description: When the external product was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external product was updated in Recurly.
external_product_references:
type: array
description: List of external product references of the external product.
items:
"$ref": "#/components/schemas/ExternalProductReference"
ExternalSubscription:
type: object
properties:
account:
type: string
description: The URL of the account for the specified external subscription.
external_product_reference:
$ref: "#/components/schemas/ExternalProductReference"
external_payment_phases:
type: array
items:
"$ref": "#/components/schemas/ExternalPaymentPhase"
uuid:
type: string
description: Universally Unique Identifier created automatically.
last_purchased:
type: string
format: date-time
description:
When a new billing event occurred on the external subscription in conjunction with a recent
billing period, reactivation or upgrade/downgrade.
auto_renew:
type: boolean
default: false
description: An indication of whether or not the external subscription will auto-renew at the expiration date.
in_grace_period:
type: boolean
title: In grace period
description: An indication of whether or not the external subscription is in a grace period.
default: false
app_identifier:
type: string
description: Identifier of the app that generated the external subscription.
quantity:
type: integer
default: "1"
description: An indication of the quantity of a subscribed item's quantity.
state:
type: string
description: External subscriptions can be active, canceled, expired, or past_due.
default: active
activated_at:
type: string
format: date-time
description: When the external subscription was activated in the external platform.
canceled_at:
type: string
format: date-time
title: Canceled at
description: When the external subscription was canceled in the external platform.
expires_at:
type: string
format: date-time
description: When the external subscription expires in the external platform.
trial_started_at:
type: string
format: date-time
title: Trial started at
description: When the external subscription trial period started in the external platform.
trial_ends_at:
type: string
format: date-time
title: Trial ends at
description: When the external subscription trial period ends in the external platform.
test:
type: boolean
title: Test
description:
An indication of whether or not the external subscription was
purchased in a sandbox environment.
default: false
imported:
type: boolean
title: Imported
description:
An indication of whether or not the external subscription was created by
a historical data import.
default: false
created_at:
type: string
format: date-time
description: When the external subscription was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external subscription was updated in Recurly.
ExternalInvoice:
type: object
properties:
id:
type: string
title: External invoice ID
description:
System-generated unique identifier for an external invoice
ID, e.g. `e28zov4fw0v2`.
object:
type: string
title: Object type
account:
"$ref": "#/components/schemas/AccountMini"
external_subscription:
"$ref": "#/components/schemas/ExternalSubscription"
external_payment_phase:
$ref: "#/components/schemas/ExternalPaymentPhase"
external_id:
type: string
description:
An identifier which associates the external invoice to a corresponding
object in an external platform.
state:
"$ref": "#/components/schemas/ExternalInvoiceStateEnum"
total:
type: string
format: decimal
title: Total
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
line_items:
type: array
items:
"$ref": "#/components/schemas/ExternalCharge"
purchased_at:
type: string
format: date-time
description: When the invoice was created in the external platform.
created_at:
type: string
format: date-time
description: When the external invoice was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external invoice was updated in Recurly.
ExternalInvoiceStateEnum:
type: string
enum:
- paid
ExternalCharge:
type: object
description:
Charge from an external resource such as Apple App Store or Google
Play Store.
properties:
id:
type: string
title: External invoice ID
description:
System-generated unique identifier for an external charge ID,
e.g. `e28zov4fw0v2`.
object:
type: string
title: Object type
account:
"$ref": "#/components/schemas/AccountMini"
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
unit_amount:
type: string
format: decimal
title: Unit Amount
quantity:
type: integer
description:
type: string
external_product_reference:
"$ref": "#/components/schemas/ExternalProductReferenceMini"
created_at:
type: string
format: date-time
title: Created at
description: When the external charge was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external charge was updated in Recurly.
ExternalProductReferenceMini:
type: object
title: External Product Reference details
description: External Product Reference details
properties:
id:
type: string
title: External Product ID
description:
System-generated unique identifier for an external product
ID, e.g. `e28zov4fw0v2`.
object:
type: string
title: object
reference_code:
type: string
title: reference_code
description:
A code which associates the external product to a corresponding
object or resource in an external platform like the Apple App Store or
Google Play Store.
external_connection_type:
type: string
title: external_connection_type
description: Source connection platform.
created_at:
type: string
format: date-time
description: When the external product was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external product was updated in Recurly.
ExternalPaymentPhase:
type: object
properties:
started_at:
type: string
format: date-time
ends_at:
type: string
format: date-time
starting_billing_period_index:
type: integer
title: Starting Billing Period Index
ending_billing_period_index:
type: integer
title: Ending Billing Period Index
offer_type:
type: string
title: Offer Type
description: Type of discount offer given, e.g. "FREE_TRIAL"
offer_name:
type: string
title: Offer Name
description: Name of the discount offer given, e.g. "introductory"
period_count:
type: integer
title: Period Count
description: Number of billing periods
period_length:
type: string
title: Period Length
description: Billing cycle length
amount:
type: string
format: decimal
title: Amount
minimum: 0
description: Allows up to 9 decimal places
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
created_at:
type: string
format: date-time
title: Created at
description: When the external charge was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external charge was updated in Recurly.
ExternalProductReferenceBase:
type: object
properties:
reference_code:
type: string
description:
A code which associates the external product to a corresponding
object or resource in an external platform like the Apple App Store or
Google Play Store.
maxLength: 255
external_connection_type:
"$ref": "#/components/schemas/ExternalProductReferenceConnectionTypeEnum"
ExternalProductReferenceConnectionTypeEnum:
type: string
enum:
- apple_app_store
- google_play_store
ExternalProductReferenceCreate:
allOf:
- "$ref": "#/components/schemas/ExternalProductReferenceBase"
required:
- reference_code
- external_connection_type
RequestError:
type: object
title: Error
properties:
type:
title: Type
"$ref": "#/components/schemas/ErrorTypeEnum"
symbol:
type: string
description:
type: string
xml:
name: error
Error:
type: object
title: Error
properties:
symbol:
type: string
description:
type: string
xml:
name: error
Errors:
type: array
items:
$ref: "#/components/schemas/Error"
xml:
name: errors
Error404:
allOf:
- $ref: "#/components/schemas/Error"
- type: object
properties:
symbol:
default: not_found
GeneralLedgerAccount:
type: object
description: Full general ledger account details.
properties:
id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
code:
"$ref": "#/components/schemas/GeneralLedgerAccountCode"
description:
"$ref": "#/components/schemas/GeneralLedgerAccountDescription"
account_type:
"$ref": "#/components/schemas/GeneralLedgerAccountTypeEnum"
created_at:
type: string
format: date-time
title: Created at
readOnly: true
updated_at:
type: string
format: date-time
title: Last updated at
readOnly: true
xml:
name: general_ledger_account
GeneralLedgerAccountsList:
type: array
items:
$ref: "#/components/schemas/GeneralLedgerAccount"
xml:
name: general_ledger_accounts
GeneralLedgerAccountCreate:
type: object
description: Create a new liability or revenue general ledger account.
properties:
code:
"$ref": "#/components/schemas/GeneralLedgerAccountCode"
description:
"$ref": "#/components/schemas/GeneralLedgerAccountDescription"
account_type:
"$ref": "#/components/schemas/GeneralLedgerAccountTypeEnum"
required:
- account_type
- code
xml:
name: general_ledger_account
GeneralLedgerAccountUpdate:
type: object
description: Update an existing general ledger account.
properties:
code:
"$ref": "#/components/schemas/GeneralLedgerAccountCode"
description:
"$ref": "#/components/schemas/GeneralLedgerAccountDescription"
xml:
name: general_ledger_account
GiftCard:
type: object
properties:
gifter_account:
type: string
description: The URL of the account that purchased the gift card.
invoice:
type: string
description: The URL of the invoice for the gift card purchase by the
`gifter_account`.
recipient_account:
type: string
description:
The URL of the account that redeemed the gift card redemption code.
Does not show until gift card is redeemed.
id:
type: integer
format: int64
description: The unique id of the gift card.
redemption_code:
type: string
description:
The unique redemption code for the gift card, generated by Recurly.
Will be 16 characters, alphanumeric, displayed uppercase, but
accepted in any case at redemption. Used by the `recipient_account`
to create a credit in the amount of the `unit_amount_in_cents` on
their account.
balance_in_cents:
type: integer
description:
The remaining credit on the `recipient_account` associated with
this gift card. Only shows once the gift card has been redeemed. Can
be used to create gift card balance displays for your customers.
currency:
type: string
description: The currency of the `unit_amount_in_cents` and `balance_in_cents`.
product_code:
type: string
description: The product code or SKU of the gift card product.
unit_amount_in_cents:
type: integer
description:
The amount of the gift card, which is the amount of the charge to
the `gifter_account` and the amount of credit that is applied to the
`recipient_account` upon successful redemption.
delivery:
type: object
description:
Block of delivery information. Includes the params `method` through
`personal_message` below.
method:
type: string
description: Whether the delivery method is `email` or `post`.
deliver_at:
type: string
format: date-time
description:
When the gift card should be delivered to the recipient. If null,
the gift card will be delivered immediately. If a datetime is
provided, the delivery will be in an hourly window, rounding down.
For example, 6:23 pm will be in the 6:00 pm hourly batch.
email_address:
type: string
description: The email address of the recipient.
first_name:
type: string
description: The first name of the recipient.
last_name:
type: string
description: The last name of the recipient.
address:
type: object
description:
Block of address information for the recipient. Includes the params
`address1` through `phone` below.
address1:
type: string
description: The first street address line of the recipient.
address2:
type: string
description: The second street address line of the recipient.
city:
type: string
description: The city of the recipient.
state:
type: string
description: The state/province of the recipient.
zip:
type: string
description: The zip/postal code of the recipient.
country:
type: string
description: The country of the recipient.
phone:
type: string
description: The phone number of the recipient.
gifter_name:
type: string
description:
The name of the gifter for the purpose of message displays to the
recipient.
personal_message:
type: string
description:
The personal message from the gifter to the recipient. 255
characters.
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
created_at:
type: string
format: date-time
description: When the gift card was purchased.
updated_at:
type: string
format: date-time
description:
When the gift card object was updated, which happens upon purchase,
delivery and redemption.
delivered_at:
type: string
format: date-time
description:
When the gift card was sent to the recipient by Recurly via email,
if method was email and the "Gift Card Delivery" email template was
enabled. This will be empty for post delivery or email delivery
where the email template was disabled.
redeemed_at:
type: string
format: date-time
description: When the gift card was redeemed by the recipient.
canceled_at:
type: string
format: date-time
description: When the gift card was canceled.
purchase_invoice:
type: string
description:
The URL of the charge invoice for the gift card redemption. If gift
cards enabled, this link should be used over the `invoice` link.
redemption_invoice:
type: string
description: The URL of the credit invoice for the gift card purchase.
GiftCardRedemption:
type: object
properties:
gift_card:
type: object
description:
The gift card object is required in order to redeem a redemption
code.
properties:
redemption_code:
type: string
default: ""
description: The redemption code for the gift card being redeemed.
example: JHD776JENN99E6DD
xml:
name: gift_card
InvoiceCollection:
type: array
items:
type: object
InvoiceTemplate:
type: object
properties:
uuid:
type: string
description:
Unique ID to identify an invoice template. Available when
the site is on a Pro or Elite plan. Used to specify which invoice
template, if any, should be used to generate invoices for the account.
name:
type: string
description: Invoice template name.
code:
type: string
description: Invoice template's unique code.
description:
type: string
description: Invoice template description.
created_at:
type: string
format: date-time
description: When the invoice template was created in Recurly.
updated_at:
type: string
format: date-time
description: When the invoice template was updated in Recurly.
MeasuredUnit:
type: object
properties:
id:
type: integer
description: Unique id of the measured unit on your site.
name:
type: string
description: Unique internal name of the measured unit on your site.
display_name:
type: string
description:
Display name for the measured unit. We recommend the singular
version. (e.g. - GB, API Call, Email).
description:
type: string
description: Optional internal description.
PerformanceObligation:
type: object
description: Performance obligation details
properties:
id:
"$ref": "#/components/schemas/PerformanceObligationId"
name:
title: Performance Obligation Name
type: string
created_at:
title: Created At
type: string
readOnly: true
format: date-time
updated_at:
title: Last updated at
type: string
readOnly: true
format: date-time
xml:
name: performance_obligation
PerformanceObligationList:
type: array
description: List of Performance Obligations
items:
"$ref": "#/components/schemas/PerformanceObligation"
xml:
name: performance_obligations
PlanFixedPricingProperties:
type: object
properties:
unit_amount_in_cents:
$ref: "#/components/schemas/Currencies"
pricing_model:
$ref: "#/components/schemas/PricingModelTypeEnum"
PlanRampPricingProperties:
type: object
properties:
ramp_intervals:
type: array
minItems: 1
maxItems: 12
items:
$ref: "#/components/schemas/PlanRampInterval"
pricing_model:
$ref: "#/components/schemas/PricingModelTypeEnum"
Plan:
type: object
oneOf:
- $ref: "#/components/schemas/PlanFixedPricing"
- $ref: "#/components/schemas/PlanRampPricing"
discriminator:
propertyName: pricing_model
mapping:
fixed: "#/components/schemas/PlanFixedPricing"
ramp: "#/components/schemas/PlanRampPricing"
PlanBase:
allOf:
- $ref: "#/components/schemas/PlanUpdateBase"
- type: object
properties:
plan_interval_unit:
type: string
default: months
description: "`days`, or `months`, defaults to `months`."
plan_interval_length:
type: integer
default: "1"
description: Plan interval length, defaults to `1`
PlanFixedPricing:
allOf:
- $ref: "#/components/schemas/PlanMini"
- $ref: "#/components/schemas/PlanFixedPricingProperties"
- $ref: "#/components/schemas/PlanBase"
PlanFixedPricingRequest:
allOf:
- $ref: "#/components/schemas/PlanFixedPricing"
- required:
- plan_code
- name
- unit_amount_in_cents
PlanMini:
type: object
properties:
plan_code:
$ref: "#/components/schemas/PlanCode"
name:
type: string
default: ""
maxLength: 255
description: Plan name. Max of 255 characters.
example: Gold Plan
PlanRampInterval:
type: object
title: Plan Ramp Interval
properties:
starting_billing_cycle:
$ref: "#/components/schemas/RampIntervalStartingBillingCycle"
unit_amount_in_cents:
$ref: "#/components/schemas/Currencies"
PlanRampPricing:
allOf:
- $ref: "#/components/schemas/PlanMini"
- $ref: "#/components/schemas/PlanRampPricingProperties"
- $ref: "#/components/schemas/PlanBase"
PlanRampPricingRequest:
allOf:
- $ref: "#/components/schemas/PlanRampPricing"
- required:
- plan_code
- name
- ramp_intervals
PlanRequest:
type: object
oneOf:
- $ref: "#/components/schemas/PlanFixedPricingRequest"
- $ref: "#/components/schemas/PlanRampPricingRequest"
discriminator:
propertyName: pricing_model
mapping:
fixed: "#/components/schemas/PlanFixedPricingRequest"
ramp: "#/components/schemas/PlanRampPricingRequest"
PlanUpdate:
type: object
oneOf:
- $ref: "#/components/schemas/PlanUpdateFixedPricing"
- $ref: "#/components/schemas/PlanUpdateRampPricing"
discriminator:
propertyName: pricing_model
mapping:
fixed: "#/components/schemas/PlanUpdateFixedPricing"
ramp: "#/components/schemas/PlanUpdateRampPricing"
PlanUpdateBase:
type: object
properties:
description:
type: string
default: ""
description: Optional plan description, not displayed.
trial_interval_unit:
type: string
default: days
description: "`days` or `months`, defaults to `days`."
trial_interval_length:
type: integer
default: "0"
description: Defaults to `0`, for no trial
trial_requires_billing_info:
type: boolean
default: ""
description:
Allow free trial subscriptions to be created without billing info.
Should not be used if billing info is needed for initial
invoice due to existing uninvoiced charges or setup fee.
success_url:
type: string
default: ""
description: URL to redirect to after signup on the hosted payment pages.
accounting_code:
type: string
default: ""
description:
"Accounting code for related invoice line items, code may only
contain the following characters: [a-z 0-9 @ - _ .]. Max of
20 characters."
revenue_schedule_type:
type: string
default: evenly
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Plan should be
recognized. When creating a Plan, available schedule types
are `never`, `evenly`, `at_range_start`, or `at_range_end`.
liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
setup_fee_accounting_code:
type: string
default: ""
description:
"Accounting code for a Setup Fee, code may only contain the
following characters: [a-z 0-9 @ - _ .]. Max of 20
characters."
setup_fee_revenue_schedule_type:
type: string
default: evenly
description:
Optional field for setting a revenue schedule type. This will
determine how revenue for the associated Plan Setup Fee
should be recognized. When creating a Plan Setup Fee,
available schedule types are `never`, `evenly`,
`at_range_start`, or `at_range_end`.
setup_fee_liability_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
setup_fee_revenue_gl_account_id:
"$ref": "#/components/schemas/GeneralLedgerAccountId"
setup_fee_performance_obligation_id:
"$ref": "#/components/schemas/PerformanceObligationId"
setup_fee_in_cents:
$ref: "#/components/schemas/Currencies"
total_billing_cycles:
type: integer
default: ""
description:
Number of billing cycles before the plan stops renewing, defaults
to `null` for continuous auto renewal.
unit_name:
type: string
default: ""
description: "*Deprecated* Unit description for the quantity, e.g. users."
display_quantity:
type: boolean
default: "false"
description:
Display the quantity field on the hosted payment page if `true`,
defaults to `false`.
cancel_url:
type: string
default: ""
description:
"*Deprecated* URL to redirect to on canceled signup on the hosted
payment pages."
tax_exempt:
type: boolean
default: ""
description:
"`true` exempts tax on the plan, `false` applies tax on the plan.
If not defined, then defaults to the Plan and Site
settings."
tax_code:
type: string
maxLength: 50
title: Tax code
description:
Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax
solution to determine taxation rules. You can pass in specific tax codes using any of
these tax integrations. For Recurly's In-the-Box tax offering you can also choose to
instead use simple values of `unknown`, `physical`, or `digital` tax codes.
auto_renew:
type: boolean
default: true
description:
Determines whether subscriptions to this plan should auto-renew
term at the end of the current term or expire.
bypass_hosted_confirmation:
type: boolean
default: ""
description:
If `true`, the customer will be sent directly to your `success_url`
after a successful signup, bypassing Recurly's hosted
confirmation page.
allow_any_item_on_subscriptions:
type: boolean
default: false
description:
Used to determine whether items can be assigned as add-ons to
individual subscriptions. If `true`, items can be assigned
as add-ons to individual subscription add-ons. If `false`,
only plan add-ons can be used.
vertex_transaction_type:
type: string
default: "sale"
description:
Used by Vertex for tax calculations. Possible values are `sale`,
`rental`, `lease`.
dunning_campaign_id:
type: string
default: ""
description:
Unique ID to identify a dunning campaign. Available when the
Dunning Campaigns feature is enabled. Used to specify if a non-default
dunning campaign should be assigned to this plan. For sites without multiple
dunning campaigns enabled, the default dunning campaign will always be
used.
custom_fields:
$ref: "#/components/schemas/CustomFields"
PlanUpdateFixedPricing:
allOf:
- $ref: "#/components/schemas/PlanMini"
- $ref: "#/components/schemas/PlanFixedPricingProperties"
- $ref: "#/components/schemas/PlanUpdateBase"
PlanUpdateRampPricing:
allOf:
- $ref: "#/components/schemas/PlanMini"
- $ref: "#/components/schemas/PlanRampPricingProperties"
- $ref: "#/components/schemas/PlanUpdateBase"
PurchaseBase:
type: object
required:
- account
- adjustments
- currency
properties:
account:
type: object
default: ""
description:
An account object. This can be an existing account or a new
account. If using a new account and adding shipping
addresses, the last shipping address in the list will apply
to every subscription and adjustment in the purchase.
billing_info_uuid:
"$ref": "#/components/schemas/BillingInfoUuid"
adjustments:
type: array
default: ""
description:
This should be a list of Adjustment objects. Required if there are
no subscriptions.
items:
$ref: "#/components/schemas/AdjustmentCreate"
collection_method:
"$ref": "#/components/schemas/CollectionMethodEnum"
currency:
"$ref": "#/components/schemas/CurrencyCode"
net_terms:
"$ref": "#/components/schemas/NetTerms"
net_terms_type:
"$ref": "#/components/schemas/NetTermsTypeEnum"
gift_card:
"$ref": "#/components/schemas/GiftCardRedemption"
coupon_codes:
"$ref": "#/components/schemas/CouponCodes"
subscriptions:
type: array
default: ""
description:
A list of Subscriptions to invoice in this purchase. Required if
there are no adjustments.
items:
oneOf:
- $ref: "#/components/schemas/SubscriptionRequest"
- $ref: "#/components/schemas/SubscriptionRequestWithFeatures"
shipping_address_id:
"$ref": "#/components/schemas/ShippingAddressId"
shipping_address:
"$ref": "#/components/schemas/ShippingAddress"
customer_notes:
"$ref": "#/components/schemas/CustomerNotes"
terms_and_conditions:
"$ref": "#/components/schemas/TermsAndConditions"
transaction:
type: object
description: (Transaction Data, Card on File) - Options for flagging transactions as Customer or Merchant Initiated Unscheduled.
allOf:
- type: object
properties:
initiator:
$ref: "#/components/schemas/Transaction/properties/initiator"
merchant_reason_code:
$ref: "#/components/schemas/Transaction/properties/merchant_reason_code"
vat_reverse_charge_notes:
"$ref": "#/components/schemas/VatReverseChargeNotes"
vertex_transaction_type:
"$ref": "#/components/schemas/VertexTransactionTypeEnum"
Purchase: # keeping things extensible
allOf:
- "$ref": "#/components/schemas/PurchaseBase"
xml:
name: purchase
Redemption:
type: object
properties:
account_code:
type: string
description: ""
redemption_uuid:
type: string
description: ""
coupon:
type: string
description: The link to the coupon used
account:
type: string
description: The link to the account
subscription:
type: string
description:
The link to the subscription (only available if redeemed on a
subscription)
uuid:
type: string
description: The unique UUID referencing this redemption.
single_use:
type: boolean
description: True if this is a single_use coupon
total_discounted_in_cents:
type: integer
description: Total in cents for the discount issued with this redemption
currency:
type: string
description: The currency used at the time of purchase
state:
type: string
description: The state of the redemption. Can be `active` or `inactive`
coupon_code:
type: string
description: The coupon code of the coupon used
created_at:
type: string
format: date-time
description: The datetime this redemption was created
updated_at:
type: string
description: The datetime this redemption was last updated
ReferenceAccount:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: account
ReferenceBillingInfo:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: billing_info
ReferenceInvoice:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: invoice
ReferencePlan:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: plan
ReferenceRedemptions:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: redemptions
ReferenceShippingAddress:
type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
xml:
name: shipping_address
ShippingAddress:
allOf:
- $ref: "#/components/schemas/AddressWithName"
- type: object
required:
- first_name
- last_name
- address1
- city
- state
- zip
- country
description: |-
Optional nested object to use if you want to create a new shipping
address on a new subscription/account. The nested object contains
the information for the account shipping address:
`first_name`, `last_name`, `company_name`, `email`, `phone`,
`vat_number`, `address1`, `address2`, `city`, `state`,
`zip`, `country`, `nickname`. When providing a shipping
address, the following are required: first_name, last_name,
address1, city, state, zip, and country. Required if using
`shipping_method_code` and no `shipping_address_id` is
specified.
properties:
first_name:
description: The first name for the account. Max of 255 characters.
last_name:
description: The last name for the account. Max of 255 characters.
phone:
description: The phone number for the shipping address.
address1:
description: Address line 1.
address2:
description: Address line 2.
city:
description: City
state:
description: State or region
zip:
description: Zip or postal code
country:
description: Country, [2-letter ISO
code](http://www.iso.org/iso/country_names_and_code_elements).
nickname:
type: string
description:
A nickname for the shipping address. Defaults to "first_name
last_name". Max of 255 characters.
maxLength: 255
default: ""
example: Work
company:
type: string
description: The company name for the shipping address. Max of 50 characters.
maxLength: 50
example: Recurly Inc
default: ""
email:
allOf:
- $ref: "#/components/schemas/Email"
- description: The email address for the shipping address.
vat_number:
type: string
description: Customer's VAT number (to avoid having VAT applied, if applicable).
default: ""
maxLength: 20
SubscriptionBase:
# all sub schemas. initially gets node name and title correct
type: object
title: Subscription
xml:
name: subscription
SubscriptionBasicResponse:
title: Subscription (Basic Features)
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
account:
$ref: "#/components/schemas/ReferenceAccount"
invoice:
$ref: "#/components/schemas/ReferenceInvoice"
- $ref: "#/components/schemas/SubscriptionSharedReferences"
- $ref: "#/components/schemas/SubscriptionSharedResponseProperties"
- $ref: "#/components/schemas/SubscriptionReferenceAnchors"
SubscriptionCommonFields:
type: object
properties:
uuid:
type: string
title: UUID
description:
The UUID is useful for matching data with the CSV exports and
building URLs into Recurly's UI.
maxLength: 32
example: 374ae5e848adcfd332fdd3469d89c888
state:
$ref: "#/components/schemas/SubscriptionStateEnum"
unit_amount_in_cents: # description specific to sub create
type: integer
maximum: 10000000
minimum: 0
description:
Override the unit amount of the subscription plan by setting this
value in cents. If not provided, the subscription will
inherit the price from the subscription plan for the
provided currency. Max 10000000.
currency:
type: string
description: 3-Letter currency code for the subscription.
example: "USD"
quantity:
type: integer
default: 1
minimum: 1
description: Optionally override the default quantity of 1.
activated_at:
type: string
format: date-time
canceled_at:
type: string
format: date-time
expires_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
total_billing_cycles:
type: integer
description:
The total number of billing cycles for the current subscription
term
minimum: 1
remaining_billing_cycles:
type: integer
description:
The number of billing periods that are left in the subscription.
`1` means the subscription renew one more time and then
expire. Decrements from the total number of billing periods
in the current term. Will always be 0 if total billing
cycles is 1.
minimum: 0
current_period_started_at:
type: string
format: date-time
current_period_ends_at:
type: string
format: date-time
trial_started_at:
type: string
format: date-time
trial_ends_at:
type: string
format: date-time
description:
If set, overrides the default trial behavior for the subscription.
This must be a date and time, preferably in UTC. If the date
is in the past, the subscription will skip the trial.
terms_and_conditions:
type: string
description:
Optional notes field. This will default to the Terms and Conditions
text specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Terms and Conditions. Custom notes will stay with a
subscription on all renewals.
customer_notes:
type: string
description:
Optional notes field. This will default to the Customer Notes text
specified on the Invoice Settings page in your Recurly
admin. Specify custom notes with this tag to add or override
Customer Notes. Custom notes will stay with a subscription
on all renewals.
action_result:
type: string
description:
Action result params to be used in Recurly-JS to complete a
payment when using asynchronous payment methods, e.g., Boleto, iDEAL and
Sofort.
SubscriptionCreatePreviewRequest:
type: object
xml:
name: subscription
oneOf:
- $ref: "#/components/schemas/SubscriptionRequest"
- $ref: "#/components/schemas/SubscriptionRequestWithFeatures"
- $ref: "#/components/schemas/SubscriptionRequestManualInvoicingWithShipping"
SubscriptionFixedPricingCreateResponse:
type: object
oneOf:
- $ref: "#/components/schemas/SubscriptionBasicResponse"
- $ref: "#/components/schemas/SubscriptionFullResponse"
xml:
name: subscription
SubscriptionFullResponse:
title: Subscription (Extended Features)
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- type: object
properties:
href:
$ref: "#/components/schemas/ReferenceHref"
account:
$ref: "#/components/schemas/ReferenceAccount"
invoice:
$ref: "#/components/schemas/ReferenceInvoice"
billing_info:
$ref: "#/components/schemas/ReferenceBillingInfo"
redemptions:
$ref: "#/components/schemas/ReferenceRedemptions"
shipping_address:
$ref: "#/components/schemas/ReferenceShippingAddress"
- $ref: "#/components/schemas/SubscriptionSharedReferences"
- $ref: "#/components/schemas/SubscriptionSharedResponseProperties"
- $ref: "#/components/schemas/SubscriptionSharedConditionalResponseProperties"
- $ref: "#/components/schemas/SubscriptionReferenceAnchors"
SubscriptionImportedTrial:
type: object
properties:
imported_trial:
$ref: "#/components/schemas/ImportedTrial"
SubscriptionInvoicing:
type: object
properties:
po_number:
type: string
default: ""
description: Optional notes field. Attach a PO number to the invoice.
net_terms:
"$ref": "#/components/schemas/NetTerms"
net_terms_type:
"$ref": "#/components/schemas/NetTermsTypeEnum"
collection_method:
$ref: "#/components/schemas/CollectionMethodEnum"
SubscriptionPausing:
type: object
properties:
remaining_pause_cycles:
type: integer
description:
Number of billing cycles to pause the subscriptions. A value
of 0 will cancel any pending pauses on the subscription.
minimum: 0
paused_at:
type: string
format: date-time
SubscriptionPreviewBasicResponse:
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- type: object
properties:
href:
type: string
default: ""
xml:
attribute: true
- $ref: "#/components/schemas/SubscriptionSharedReferences"
- $ref: "#/components/schemas/SubscriptionSharedResponseProperties"
- $ref: "#/components/schemas/SubscriptionPreviewSharedResponseProperties"
SubscriptionPreviewFullResponse:
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- type: object
properties:
href:
type: string
default: ""
xml:
attribute: true
- $ref: "#/components/schemas/SubscriptionSharedReferences"
- $ref: "#/components/schemas/SubscriptionSharedResponseProperties"
- $ref: "#/components/schemas/SubscriptionSharedConditionalResponseProperties"
- $ref: "#/components/schemas/SubscriptionPreviewSharedResponseProperties"
SubscriptionPreviewResponse:
type: object
xml:
name: subscription
oneOf:
- $ref: "#/components/schemas/SubscriptionPreviewBasicResponse"
- $ref: "#/components/schemas/SubscriptionPreviewFullResponse"
SubscriptionPreviewSharedResponseProperties:
type: object
properties:
address:
$ref: "#/components/schemas/AddressWithNameResponse"
cost_in_cents:
$ref: "#/components/schemas/CostInCents"
invoice_collection:
$ref: "#/components/schemas/InvoiceCollection"
SubscriptionRampInterval:
type: object
title: Subscription Ramp Interval
properties:
starting_billing_cycle:
$ref: "#/components/schemas/RampIntervalStartingBillingCycle"
unit_amount_in_cents:
type: integer
description: Represents the price for the ramp interval.
minimum: 0
xml:
name: ramp_interval
SubscriptionRampIntervalResponse:
allOf:
- $ref: "#/components/schemas/SubscriptionRampInterval"
- properties:
remaining_billing_cycles:
type: integer
minimum: 0
description: Represents how many billing cycles are left in a ramp interval.
starting_on:
type: string
format: date-time
description: Date the ramp interval starts.
ending_on:
type: string
format: date-time
description: Date the ramp interval ends.
SubscriptionRampIntervals:
type: object
properties:
ramp_intervals:
type: array
items:
$ref: "#/components/schemas/SubscriptionRampInterval"
xml:
wrapped: true
SubscriptionRampIntervalsResponse:
type: object
properties:
ramp_intervals:
type: array
items:
$ref: "#/components/schemas/SubscriptionRampIntervalResponse"
xml:
wrapped: true
SubscriptionReferenceAnchorCancel:
type: object
properties:
name:
type: string
enum:
- cancel
xml:
attribute: true
href:
$ref: "#/components/schemas/ReferenceHref"
method:
$ref: "#/components/schemas/PutMethodAttribute"
xml:
name: a
SubscriptionReferenceAnchorNotes:
type: object
properties:
name:
type: string
enum:
- notes
xml:
attribute: true
href:
$ref: "#/components/schemas/ReferenceHref"
method:
$ref: "#/components/schemas/PutMethodAttribute"
xml:
name: a
SubscriptionReferenceAnchorPostpone:
type: object
properties:
name:
type: string
enum:
- postpone
xml:
attribute: true
href:
$ref: "#/components/schemas/ReferenceHref"
method:
$ref: "#/components/schemas/PutMethodAttribute"
xml:
name: a
SubscriptionReferenceAnchorReactivate:
type: object
properties:
name:
type: string
enum:
- reactivate
xml:
attribute: true
href:
$ref: "#/components/schemas/ReferenceHref"
method:
$ref: "#/components/schemas/PutMethodAttribute"
xml:
name: a
SubscriptionReferenceAnchorTerminate:
type: object
properties:
name:
type: string
enum:
- terminate
xml:
attribute: true
href:
$ref: "#/components/schemas/ReferenceHref"
method:
$ref: "#/components/schemas/PutMethodAttribute"
xml:
name: a
SubscriptionReferenceAnchors:
type: object
properties:
cancel:
$ref: "#/components/schemas/SubscriptionReferenceAnchorCancel"
terminate:
$ref: "#/components/schemas/SubscriptionReferenceAnchorTerminate"
postpone:
$ref: "#/components/schemas/SubscriptionReferenceAnchorPostpone"
notes:
$ref: "#/components/schemas/SubscriptionReferenceAnchorNotes"
SubscriptionRequest:
title: Subscription (Basic Features)
xml:
name: subscription
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- type: object
required:
- plan_code
- account
- currency
properties:
plan_code:
$ref: "#/components/schemas/PlanCode"
currency:
$ref: "#/components/schemas/CurrencyCode"
account:
allOf:
- $ref: "#/components/schemas/AccountMini"
- properties:
billing_info:
$ref: "#/components/schemas/BillingInfoCC"
quantity:
$ref: "#/components/schemas/Quantity"
unit_amount_in_cents: # description specific to sub create
type: integer
maximum: 10000000
minimum: 0
description: Override the unit amount of the subscription plan by
setting this value in cents. If not provided, the subscription
will inherit the price from the subscription plan for the
provided currency. Max 10000000.
total_billing_cycles:
$ref: "#/components/schemas/TotalBillingCycles"
renewal_billing_cycles:
$ref: "#/components/schemas/RenewalBillingCycles"
revenue_schedule_type:
$ref: "#/components/schemas/RevenueScheduleTypeEnum"
trial_ends_at:
$ref: "#/components/schemas/TrialEndsAt"
imported_trial:
$ref: "#/components/schemas/ImportedTrial"
starts_at:
$ref: "#/components/schemas/StartsAt"
next_bill_date:
type: string
format: date-time
default: ""
description:
Indicates the subscription's next billing period start date.
Subsequent billing period start dates will be offset from
this date. The first invoice will be prorated appropriately
so that the customer only pays for the portion of the first
billing period for which the subscription applies. Useful
for forcing a subscription to bill on the first of the
month.
coupon_code:
$ref: "#/components/schemas/CouponCode"
terms_and_conditions:
$ref: "#/components/schemas/TermsAndConditions"
customer_notes:
$ref: "#/components/schemas/CustomerNotes"
bulk:
type: boolean
description:
Optional field to be used only when needing to bypass the 60 second
limit on creating subscriptions. Should only be used when
creating subscriptions in bulk from the API. Set to `true`
or `false`. Defaults to `false`.
default: false
transaction_type: # this isn't in the response..
type: string
description: An optional type designation for the payment gateway
transaction created by this request. Supports `'moto'` value,
which is the acronym for mail order and telephone transactions.
enum:
- moto
default: ""
subscription_add_ons:
$ref: "#/components/schemas/SubscriptionAddOns"
custom_fields:
$ref: "#/components/schemas/CustomFields"
proration_settings:
"$ref": "#/components/schemas/ProrationSettings"
- $ref: "#/components/schemas/GiftCardRedemption"
- $ref: "#/components/schemas/SubscriptionInvoicing"
SubscriptionRequestManualInvoicingWithShipping:
title: Manual Invoicing with Shipping
allOf:
- $ref: "#/components/schemas/SubscriptionBase"
- allOf:
- $ref: "#/components/schemas/SubscriptionInvoicing"
- properties:
shipping_amount_in_cents:
example: 999
collection_method:
example: manual
- $ref: "#/components/schemas/SubscriptionShipping"
- type: object
required:
- plan_code
- account
- currency
properties:
plan_code:
$ref: "#/components/schemas/PlanCode"
currency:
$ref: "#/components/schemas/CurrencyCode"
account:
allOf:
- $ref: "#/components/schemas/AccountMini"
- properties:
billing_info:
$ref: "#/components/schemas/BillingInfoCC"
shipping_address:
$ref: "#/components/schemas/ShippingAddress"
SubscriptionRequestWithFeatures:
title: Subscription (Extended Features)
allOf:
- $ref: "#/components/schemas/SubscriptionRequest"
- type: object
properties:
billing_info_uuid:
type: string
description:
The `billing_info_uuid` is the value that represents a specific
billing info for an end customer. When `billing_info_uuid` is used to assign
billing info to the subscription, all future billing events for the subscription
will bill to the specified billing info. `billing_info_uuid` can ONLY be
used for sites utilizing the Wallet feature.
coupon_codes:
$ref: "#/components/schemas/CouponCodes"
tax_inclusive:
$ref: "#/components/schemas/TaxInclusive"
vat_reverse_charge_notes:
$ref: "#/components/schemas/VatReverseChargeNotes"
bank_account_authorized_at: # only for update?
$ref: "#/components/schemas/BankAccountAuthorizedAt"
shipping_address:
$ref: "#/components/schemas/ShippingAddress"
shipping_address_id:
type: string
default: ""
description:
Optional field to use when you want to associate an existing
shipping address with a new subscription. Required if using
`shipping_method_code` and no `shipping_address` is
specified.
- $ref: "#/components/schemas/SubscriptionRampIntervals"
- $ref: "#/components/schemas/SubscriptionShipping"
SubscriptionSharedConditionalResponseProperties:
# i.e. extended features that show in both previewed and persisted responses
allOf:
- $ref: "#/components/schemas/TaxInfo"
- $ref: "#/components/schemas/SubscriptionInvoicing"
- $ref: "#/components/schemas/SubscriptionShipping"
- $ref: "#/components/schemas/SubscriptionRampIntervalsResponse"
- type: object
properties:
vat_reverse_charge_notes:
$ref: "#/components/schemas/VatReverseChargeNotes"
tax_inclusive:
$ref: "#/components/schemas/TaxInclusive"
bank_account_authorized_at:
$ref: "#/components/schemas/BankAccountAuthorizedAt"
# pending_subscription: maybe undocumented?
SubscriptionSharedReferences:
# these always show in sub responses. use other
# reference $refs for specific endpoint paths
type: object
properties:
plan:
allOf:
- $ref: "#/components/schemas/ReferencePlan"
- $ref: "#/components/schemas/PlanMini"
SubscriptionSharedResponseProperties:
# i.e. basic features that show in previewed AND persisted responses
allOf:
- $ref: "#/components/schemas/SubscriptionTerms"
- $ref: "#/components/schemas/SubscriptionCommonFields"
- $ref: "#/components/schemas/SubscriptionStartedWithGift"
- $ref: "#/components/schemas/SubscriptionImportedTrial"
- $ref: "#/components/schemas/SubscriptionPausing"
- type: object
properties:
revenue_schedule_type:
$ref: "#/components/schemas/RevenueScheduleTypeEnum"
no_billing_info_reason:
type: string
default: ""
gateway_code:
type: string
default: ""
description:
An alphanumeric code shown per gateway on your site's payment
gateways page. Set this code to ensure that a given
subscription targets a given gateway.
subscription_add_ons:
$ref: "#/components/schemas/SubscriptionAddOns"
custom_fields:
$ref: "#/components/schemas/CustomFields"
action_result:
type: string
description:
Action result params to be used in Recurly-JS to complete a
payment when using asynchronous payment methods, e.g., Boleto, iDEAL and
Sofort.
SubscriptionShipping:
type: object
description: Subscription shipping details
properties:
shipping_amount_in_cents:
type: integer
minimum: 0
shipping_method_code:
type: string
description: The reference code for the shipping method used, such as
shipping_method.code `'fedex_ground'`. Required if
`shipping_amount_in_cents` is specified.
example: fedex_ground
SubscriptionsListResponse:
xml:
name: subscriptions
wrapped: true
allOf:
- properties:
type:
type: string
enum:
- array
default: array
- oneOf:
- type: array
items:
$ref: "#/components/schemas/SubscriptionBasicResponse"
- type: array
items:
$ref: "#/components/schemas/SubscriptionFullResponse"
SubscriptionStartedWithGift:
type: object
properties:
started_with_gift:
type: boolean
default: false
converted_at:
type: string
format: date-time
SubscriptionTerms:
type: object
properties:
auto_renew:
type: boolean
default: true
description:
Determines if subscription configured to auto renew for another
term or expire at the end of current term.
renewal_billing_cycles:
type: integer
description:
The number of billing periods in the subscription's next term. Will
default to the plan's total_billing_cycles unless specified.
current_period_started_at:
type: string
format: date-time
current_period_ends_at:
type: string
format: date-time
TaxInfo:
type: object
properties:
tax_in_cents:
type: integer
minimum: 0
tax_type:
type: string
description:
Provides the tax type as "vat" for EU VAT, "usst" for U.S.
Sales Tax, or the 2 letter country code for country level tax types like
Canada, Australia, New Zealand, Israel, and all non-EU European countries.
example: usst
tax_region:
type: string
description:
Provides the tax region applied on an invoice. For U.S. Sales
Tax, this will be the 2 letter state code. For EU VAT this will be the
2 letter country code. For all country level tax types, this will display
the regional tax, like VAT, GST, or PST.
example: CO
tax_rate:
type: number
format: float
title: Rate
example: 0.0725
Transaction:
type: object
properties:
uuid:
type: string
description: The unique identifier of the transaction.
account:
type: string
description: The URL of the account associated with the transaction.
initiator:
type: string
description: Must be sent for one-time transactions in order to provide context on which entity is submitting the transaction to ensure proper fraud checks are observed, such as 3DS. If the customer is in session, send `customer`. If this is a merchant initiated one-time transaction, send `merchant`.
enum:
- customer
- merchant
invoice:
type: string
description: The URL of the invoice associated with the transaction.
merchant_reason_code:
type: string
default: none
description: |
This conditional parameter is useful for merchants in specific industries who need to submit one-time Merchant Initiated transactions in specific cases.
Not all gateways support these methods, but will support a generic one-time Merchant Initiated transaction.
Only use this if the initiator value is "merchant". Otherwise, it will be ignored.
- Incremental: Send `incremental` with an additional purchase if the original authorization amount is not sufficient to cover the costs of your service or product. For example, if the customer adds goods or services or there are additional expenses.
- No Show: Send `no_show` if you charge customers a fee due to an agreed-upon cancellation policy in your industry.
- Resubmission: Send `resubmission` if you need to attempt collection on a declined transaction. You may also use the force collection behavior which has the same effect.
- Service Extension: Send `service_extension` if you are in a service industry and the customer has increased/extended their service in some way. For example: adding a day onto a car rental agreement.
- Split Shipment: Send `split_shipment` if you sell physical product and need to split up a shipment into multiple transactions when the customer is no longer in session.
- Top Up: Send `top_up` if you process one-time transactions based on a pre-arranged agreement with your customer where there is a pre-arranged account balance that needs maintaining. For example, if the customer has agreed to maintain an account balance of 30.00 and their current balance is 20.00, the MIT amount would be at least 10.00 to meet that 30.00 threshold.
enum:
- incremental
- no_show
- resubmission
- service_extension
- split_shipment
- top_up
subscription:
type: string
description: The URL of the subscription associated with the transaction.
original_transaction:
type: object
description: For refund transactions, the URL of the original transaction.
action:
type: string
description: "`purchase`, `verify` or `refund`."
amount_in_cents:
type: integer
description: Total transaction amount in cents.
tax_in_cents:
type: integer
description: Amount of tax or VAT within the transaction, in cents.
currency:
type: string
description: 3-letter currency for the transaction.
status:
type: string
description: "`success`, `declined`, or `void`."
payment_method:
type: string
description: "`credit_card`, `paypal`, `check`, `wire_transfer`, `money_order`."
reference:
type: string
description: Transaction reference from your payment gateway.
source:
type: string
description:
"Source of the transaction. Possible values: `transaction` for
one-time transactions, `subscription` for subscriptions,
`billing_info` for updating billing info."
recurring:
type: boolean
description: True if transaction is recurring.
test:
type: boolean
description: True if test transaction.
voidable:
type: boolean
description:
True if the transaction may be voidable, accuracy depends on your
gateway.
refundable:
type: string
description: True if the transaction may be refunded.
ip_address:
type: string
description: Customer's IP address on the transaction, if applicable.
cvv_result:
type: string
description: CVV result, if applicable.
avs_result:
type: string
description: AVS result, if applicable.
avs_result_street:
type: string
description: AVS result for the street address, line 1.
avs_result_postal:
type: string
description: AVS result for the postal code.
created_at:
type: string
format: date-time
description: Date the transaction took place.
updated_at:
type: string
format: date-time
description: Date the transaction was last modified.
details:
type: string
description:
Nested account and billing information submitted at the time of the
transaction. When writing a client library, do not map these
directly to Account or Billing Info objects.
origin:
type: string
description:
Describes how the transaction was triggered. May be one of
(api,hpp,merchant,recurly_admin,recurlyjs,recurring,transparent,force_collect,refunded_externally,chargeback,external_recovery).
collected_at:
type: string
format: date-time
description:
When the transaction was collected, or if not collected yet, the
time the transaction was created.
description:
type: string
description: The description that gets sent to the gateway.
message:
type: string
description: The message from the gateway.
approval_code:
type: string
description: The approval code that comes back from the gateway
gateway_type:
type: string
description: Identifies the payment gateway used to process the transaction.
action_result:
type: string
description:
Action result params to be used in Recurly-JS to complete a
payment when using asynchronous payment methods, e.g., Boleto, iDEAL and
Sofort.
required:
- uuid
Usage:
type: object
properties:
subscription_uuid:
type: string
description: Subscription's unique identifier.
add_on_code:
type: string
description: The unique add-on code.
measured_unit:
type: string
description:
The URL of the measured unit associated with the add-on the usage
record is for.
amount:
type: integer
description:
The amount of usage. Can be positive, negative, or 0. If the
Decimal Quantity feature is enabled, this value will be rounded to nine
decimal places for requests. Otherwise, all digits after the decimal will be stripped.
If the usage-based add-on is billed with a percentage, your usage should
be a monetary amount formatted in cents (e.g., $5.00 is "500").
amount_decimal:
type: number
format: float
description:
A floating-point alternative for the amount of usage. Can be positive,
negative, or 0. If the Decimal Quantity feature is enabled, this value will be rounded
to nine decimal places for requests. Otherwise, this field will not be used.
merchant_tag:
type: string
description:
Custom field great for recording the id in your own system
associated with the usage, so you can provide auditable usage
displays to your customers using a GET on this endpoint.
recording_timestamp:
type: string
format: date-time
description: When the usage was recorded in your system.
usage_timestamp:
type: string
format: date-time
description:
When the usage actually happened. This will define the line item
dates this usage is billed under and is important for revenue
recognition.
created_at:
type: string
format: date-time
description: When the usage record was created in Recurly.
updated_at:
type: string
format: date-time
description: When the usage record was updated. Will be `null` after creation.
billed_at:
type: string
format: date-time
description: When the usage record was billed on an invoice.
usage_type:
type: string
description:
Whether the associated add-on has a pricing model of "price per
unit" (`price`) or "percentage of an amount" (`percentage`)
unit_amount_in_cents:
type: integer
description:
If `usage_type` = `price`, this is the price of the add-on at the
`usage_timestamp` time and the price at which the usage will be
billed on the invoice.
usage_percentage:
$ref: "#/components/schemas/UsagePercentage"
tier_type:
type: string
default: flat
description:
The pricing model for the add-on. Defaults to `flat`. Other
options include `tiered`, `volume` or `stairstep`. Cannot be
changed once saved. For more information, [click
here](https://docs.recurly.com/docs/billing-models#section-quantity-based).
tiers:
$ref: "#/components/schemas/Tiers"
percentage_tiers:
$ref: "#/components/schemas/SubscriptionPercentageTiers"
required:
- subscription_uuid
- add_on_code
UsagePercentage:
type: string
pattern: ^(100(\.0{1,4})?|\d{1,2}(\.\d{1,4})?)$
description:
The percentage taken of the monetary amount of usage tracked. This
can be up to 4 decimal places. A value between 0.0000 and 100.
Required if `add_on_type` is usage, `usage_type` is percentage
and `tier_type` = `flat`. Must be omitted otherwise.
For percentage tiered add ons use the percentage_tiers object.
# shared examples are great to keep things DRY for similar endpoints.
# additionally, if all examples are defined in the same place (i.e. here)
# then it makes it easier to ensure that sample request info shows up
# in the sample response(s) (e.g. `plan_code` value in request shows up in
# resulting plan/sub in the response). the examples below would benefit from
# either 1) a better naming convention or 2) a deviation from the alphanumeric
# sorting pattern for schemas. generally, it may be best to keep associated
# requests/responses together.
examples:
AddOnFixed:
summary: Fixed Use Add On
value: |-
video_streamingVideo Streaming1false5045usagetruepriceevenly2016-08-03T15:25:09Z2016-08-03T15:25:09Zty4utwr0mrgztwyyzw8vcm367ps
AddOnUsage:
summary: Usage Based Add On
value: |-
video_streamingVideo Streaming1false5045usagetrueprice2016-07-14T21:50:42Z2016-07-14T21:50:42Zty4utwr0mrgztwyyzw8vcm367ps
AddOnItemBacked:
summary: Item Backed Add On
value: |-
shirts_123t-shirt-12345T-Shirt (Purple)1false150150custome_teesfixedtrueevenly2019-12-07T14:49:21Z2019-12-07T14:49:21Zty4utwr0mrgztwyyzw8vcm367ps
AddOnQuantityBased:
summary: Quantity Based Pricing Add On
value: |-
planterPlanter1false200050009999999993500fixedtrueevenlytiered2036-03-25T04:44:19Z2036-03-25T04:44:19Zty4utwr0mrgztwyyzw8vcm367ps
AddOnItemBackedQuantityBased:
summary: Item Backed Qauntity Based Add On
value: |-
gs-skuactivegolden_sneakerGolden Sneaker1true200050009999999993500fixedtrueevenlytiered2020-05-28T19:54:41Z2020-05-28T19:54:41Zty4utwr0mrgztwyyzw8vcm367ps
AddOnUseageQauntityBased:
summary: Usage Quantity Based Add On
value: |-
planterplanter1true200050009999999993500usagetruepricetiered2020-07-30T23:14:35Z2020-07-30T23:14:35Zty4utwr0mrgztwyyzw8vcm367ps
PerformanceObligationsResponse:
summary: One Performance Obligation
value: |-
6Over Time (Daily)2023-08-11T18:57:57Z2023-08-11T18:57:57Z
PerformanceObligationsListResponse:
summary: All Performance Obligations
value: |-
6Over Time (Daily)2023-08-11T18:57:57Z2023-08-11T18:57:57Z5Over Time (Partial Monthly)2023-08-11T18:57:57Z2023-08-11T18:57:57Z4Point in Time2023-08-11T18:57:57Z2023-08-11T18:57:57Z
GeneralLedgerAccountCreateRequest:
summary: Create a General Ledger Account
value: |-
liability350Loch Ness
GeneralLedgerAccountUpdateRequest:
summary: Update a General Ledger Account
value: |-
350Loch Ness
GeneralLedgerAccountResponse:
summary: One General Ledger Account
value: |-
tr8dacswuk0n350liabilityLoch Ness2023-10-18T20:56:25Z2023-10-18T20:56:25Z
GeneralLedgerAccountsListResponse:
summary: All General Ledger Account
value: |-
ty0r8j3km4jnrevenue_coderevenueI AM REVENUE2023-11-22T02:49:17Z2023-11-22T02:52:51Ztr8f9wdjffc6liability_codeliabilityI AM LIABILITY2023-10-18T21:07:33Z2023-10-25T16:18:19Z
GiftCardResponse:
summary: A Gift Card
value: |-
2003020297591186183518822D87268C142500gift_card1000USDpostjohn@example.comJohnSmith123 B St.San FranciscoCA94110USASally
Hi John, Happy Birthday! I hope you have a great day! Love, Sallyt5ejtgf1vxt5ejtgf2rft5ejtge1xw2016-07-26T15:23:46Z2016-07-29T04:25:39Z2016-07-29T04:25:38Z
# may likely need to have separate examples for update since
# plan/account code etc are unnecessary for that operation
PlanFixedPricingRequest:
summary: Fixed Pricing
value: |-
gold-planGold Planfixed1months600045001000800salesizelarge
PlanFixedPricingResponse:
summary: Fixed Pricing
value: |-
gold-planGold Planfixedfalsefalsefalsefalseunit1months0days2016-08-03T15:22:50Z2016-08-03T15:22:50Zevenlyevenlyfalsetruetrue600045001000800salesizelarge
PlanRampPricingRequest:
summary: Ramp Pricing
value: |-
gold-ramped-planGold Ramped Planramp1600045006900067001000800salesizelarge
PlanRampPricingResponse:
summary: Ramp Pricing
value: |-
gold-ramped-planGold Ramped Planrampfalsefalsefalsefalseunit1months0days2016-08-03T15:22:50Z2016-08-03T15:22:50Zevenlyevenlyfalsetruetrue1600045006900067001000800salesizelarge
PlanWithRevRecRequest:
summary: With Recurly RevRec
value: |-
gold-planGold Planfixed1months600045001000800ty4utwr0mrgztwyyzw8vcm367pstwywqfr48v9ltejv6lw4eovy7pu
PlanWithRevRecResponse:
summary: With Recurly RevRec
value: |-
gold-planGold Planfixedfalsefalsefalsefalseunit1months0daysty4utwr0mrgztwyyzw8vcm367pstwywqfr48v9ltejv6lw4eovy7pu2016-08-03T15:22:50Z2016-08-03T15:22:50Zevenlyevenlyfalsetruetrue600045001000800sizelarge
# purchase endpoints need examples added for responses
PurchaseWithBillingInfoExistingRequest:
summary: Purchase with existing billing info
value: |-
automaticUSDSome notes for the customer.Our company terms and conditions.merchantresubmissionVat reverse charge notes.c442b36c-c64f-41d7-b8e1-9c04e7a6ff82verena@example.comiiznlrvdt05b
... existing adjustment fields
... existing subscription fields
... existing shipping_fee fields
... existing shipping_address fields
coupon1coupon2ABC1234
PurchaseWithBillingInfoNewRequest:
summary: Purchase with new billing info
value: |-
automaticUSDSome notes for the customer.Our company terms and conditions.customernoneVat reverse charge notes.c442b36c-c64f-41d7-b8e1-9c04e7a6ff82verena@example.com400 Alabama StSan FranciscoUSBenjaminDu Monde124111-1111-1111-1111CA2019941104549449c-5870-4845-b672-1d07f15e87dd1at_invoice1000Description of this adjustmentsizelargety4utwr0mrgztwyyzw8vcm367psplan1fast_fast_fast999LonDoner221B Baker St.LondonW1K 6AHGBHomecoupon1coupon2ABC1234
PurchaseWithRampIntervalsOverrideRequest:
summary: Purchase with custom ramp-intervals
value: |-
automaticUSDSome notes for the customer.Our company terms and conditions.merchantincrementalVat reverse charge notes.c442b36c-c64f-41d7-b8e1-9c04e7a6ff82verena@example.comiiznlrvdt05b
... existing adjustment fields
gold11994500
... existing shipping_fee fields
... existing shipping_address fields
coupon1coupon2ABC1234
PurchaseWithSubscriptionAddOnsRequest:
summary: Purchase with subscription add-ons
value: |-
maroongold3verena@example.comautomaticUSDLonDoner221B Baker St.LondonW1K 6AHGBHomeplan1addon11
SubscriptionFixedPricingCreateResponse:
summary: Subscription Created
value: |-
goldGold planevenly43ae00fadf77887688fe9c4041b7af19active4500EUR12018-03-19T17:01:48Z2018-03-19T17:01:49Z2018-03-19T17:01:48Z2018-04-19T17:01:48Zfalsefalse383usstCA0.0850netautomatic999fast_fast_fast4
true2018-06-25T21:35:49Z2019-06-25T21:35:49Zsizelarge
{"type": "redirect", "url": "https://example.test/confirm"}
SubscriptionFixedPricingResponse:
summary: Fixed Pricing
value: >-
goldGold planfixedfalsefalsefalsefalseunit1months0days2016-08-03T15:22:50Z2016-08-03T15:22:50Zevenlyevenlyfalsetruetrue600045001000800
SubscriptionListResponse:
summary: A List of Subscriptions
value: |-
goldGold planevenly3c42a34d1442f840373a4b40de85a80aexpired4500EUR12017-03-15T21:20:36Z2017-03-15T21:20:51Z2017-03-15T21:20:51Z2017-03-15T21:20:51Z2017-03-15T21:20:36Z2017-04-15T21:20:36Zfalsefalse383usstCA0.0850netautomaticsizelarge
RampSubscriptionListResponse:
summary: A List of Ramp Subscriptions
value: |-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-09-26T15:08:19Z119922023-07-26T15:08:19Z2023-11-26T15:08:19Z45002023-11-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bactive199USD12023-07-26T15:08:19Z2023-07-26T19:07:56Z102023-07-26T15:08:19Z2023-08-26T15:08:19Zfalsefalse2023-08-26T15:08:19Z10netmanual0
SubscriptionPreviewRequest:
summary: With New Account/Billing Info and Shipping Address
value: |-
goldUSDmanual01verena@example.comVerenaExample4111-1111-1111-1111122038WorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101San FranciscoCA94105USfedex_ground999
SubscriptionPreviewResponse:
summary: Subscription Preview With Existing Account
value: |-
Verena Example123 Main St.Suite 101Grand RapidsMI49506US555-222-1212goldGold planfalse42018-06-26T22:58:01Z2019-06-26T22:58:01Zevenly43adfe5232e396b129c2dd4602a0157dactive6000USD12018-03-19T16:58:54Z2018-03-19T16:58:54Z2018-04-19T16:58:54Zfalsefalse6510510usstCA0.0850netmanual999fast_fast_fast123 Main St.San FranciscoCA94105USVerena Example123 Main St.Suite 101Grand RapidsMI49506US555-222-121243adfe52c21cbb221557a24940bcd7e5pending07000USD2018-03-20T16:58:54Z7000700002018-03-20T16:58:54Z7000chargepurchase70000netmanual
SubscriptionRampPricingOverrideRequest:
summary: Ramp Pricing (Overriding Plan Ramps)
value: |-
gold-ramped-planEUR11550056600
SubscriptionRampPricingResponse:
summary: Ramp Pricing
value: >-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-08-26T15:08:19Z1550022023-07-26T15:08:19Z2023-10-26T15:08:19Z566002023-10-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bactive199USD12023-07-26T15:08:19Z2023-07-26T15:08:58Z102023-07-26T15:08:19Z2023-08-26T15:08:19Zfalsefalse0netmanual0
SubscriptionRampPricingCancelResponse:
summary: Ramp Pricing
value: >-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-08-26T15:08:19Z1550022023-07-26T15:08:19Z2023-10-26T15:08:19Z566002023-10-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bcanceled199USD12023-07-26T15:08:19Z2023-07-26T18:39:21Z2023-08-26T15:08:19Z2023-07-26T18:39:22Z102023-07-26T15:08:19Z2023-08-26T15:08:19Zfalsefalse0netmanual0
SubscriptionRampPricingPauseResponse:
summary: Ramp Pricing
value: >-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-08-26T15:08:19Z1550022023-07-26T15:08:19Z2023-10-26T15:08:19Z566002023-10-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bactive199USD12023-07-26T15:08:19Z2023-07-26T19:07:56Z102023-07-26T15:08:19Z2023-08-26T15:08:19Zfalsefalse2023-08-26T15:08:19Z10netmanual0
SubscriptionRampPricingNotesResponse:
summary: Ramp Pricing
value: >-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-08-26T15:08:19Z1550022023-07-26T15:08:19Z2023-10-26T15:08:19Z566002023-10-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bactive199USD12023-07-26T15:08:19Z2023-07-26T19:07:56Z102023-07-26T15:08:19Z2023-08-26T15:08:19ZPayment can be sent to Acme Cloud, Inc.Thanks for your business!falsefalse2023-08-26T15:08:19Z10netmanual0foodtaco
SubscriptionRampPricingConvertTrialResponse:
summary: Ramp Pricing
value: >-
gold-ramped-planGold ramped plantrue12023-07-26T15:08:19Z2023-08-26T15:08:19Z1550022023-07-26T15:08:19Z2023-10-26T15:08:19Z566002023-10-26T15:08:19Zevenly6b0189a8d767d35c0b33f34f1a9b642bactive199USD12023-07-24T20:21:44Z2023-07-27T16:14:08Z102023-07-27T16:14:00Z2024-07-27T16:14:00Z2023-07-27T16:14:00ZPayment can be sent to Acme Cloud, Inc.Thanks for your business!falsefalse0netautomatic0foodtaco
SubscriptionUpdateFixedPricingRequest:
summary: Updating a fixed-price subscription
value: |-
100now2silveriiznlrvdt8pyWorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101Grand RapidsMI49506USfull_amountfull_amount
SubscriptionUpdateFixedPricingResponse:
summary: Updated fixed-price subscription
value: |-
Verena Example123 Main St.Suite 101San FranciscoCA94105US555-222-1212goldGold planevenly43ae00fadf77887688fe9c4041b7af19active100EUR22018-03-19T17:01:48Z2018-03-19T17:01:49Z12112018-03-19T17:01:48Z2018-04-19T17:01:48Zfalsefalse21818usstCA0.0850netautomaticsizelarge
SubscriptionUpdatePreviewFixedPricingResponse:
summary: Fixed Pricing
value: |-
Verena Example123 Main St.Suite 101San FranciscoCA94105US555-222-1212goldGold planevenly43ae00fadf77887688fe9c4041b7af19active100EUR22018-03-19T17:01:48Z2018-03-19T17:01:49Z12112018-03-19T17:01:48Z2018-04-19T17:01:48Zfalsefalse21818usstCA0.0850netautomaticsizelarge123 Main St.San FranciscoCA94105USVerena Example123 Main St.Suite 101San FranciscoCA94105US555-222-121243ae03bcac4991f6d4ab2442aaa0928dopen-344-4394EUR-4400-4050-350-4394creditimmediate_changeusstCA0.085
SubscriptionUpdateRampPricingRequest:
summary: Updating a ramp-priced subscription
value: |-
now2silveriiznlrvdt8py11994500WorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101Grand RapidsMI49506US
SubscriptionUpdateRampPricingResponse:
summary: Updated ramp-priced subscription
value: |-
Verena Example123 Main St.Suite 101San FranciscoCA94105US555-222-1212goldGold plan119932018-03-26T15:08:19Z2018-07-26T15:08:19Z45002018-07-26T15:08:19Zevenly43ae00fadf77887688fe9c4041b7af19active199EUR12018-03-19T17:01:48Z2018-03-19T17:01:49Z12112018-03-19T17:01:48Z2018-04-19T17:01:48Zfalsefalse21617usstCA0.0850netautomaticsizelarge
SubscriptionUpdatePreviewRampPricingResponse:
summary: Ramp Pricing
value: |-
Verena Example123 Main St.Suite 101San FranciscoCA94105US555-222-1212goldGold plan119932018-03-26T15:08:19Z2018-07-26T15:08:19Z45002018-07-26T15:08:19Zevenly43ae00fadf77887688fe9c4041b7af19active199EUR12018-03-19T17:01:48Z2018-03-19T17:01:49Z12112018-03-19T17:01:48Z2018-04-19T17:01:48Zfalsefalse21617usstCA0.0850netautomaticsizelarge123 Main St.San FranciscoCA94105USVerena Example123 Main St.Suite 101San FranciscoCA94105US555-222-121243ae03bcac4991f6d4ab2442aaa0928dopen-344-4394EUR-4400-4050-350-4394creditimmediate_changeusstCA0.085
SubscriptionUpdatePreviewQuantityBasedPercentage:
summary: With tiered usage and term based add-ons
value: |-
Paulo Pinhorua testeRecifePernambuco55555US5_abril5 de abriltrue122022-04-06T19:27:19Z2023-04-06T19:27:19Zevenly616f23b68a74550d457fee4d6385d8feactive0USD12022-04-06T19:27:19Z2022-04-06T19:27:20Z12112022-04-06T19:27:19Z2022-05-06T19:27:19Zfalsefalse00netautomatic0usage5 de abril1percentagesubscription_termtiered10.0plan_add_onPauloPinhorua testeRecifePernambuco55555US6173554634060ee2cf559e460d9fea03pending00USD2022-04-07T14:59:56Z0002022-04-07T14:59:56Z0chargeimmediate_change00netautomatic0617355459bcb2a727ab66b46d3b2ff49pending5 de abril: 10% of $0.005 de abrilusage_add_on01000USD2022-04-06T19:27:19Z2022-04-07T14:59:55Z
SubscriptionWithAddOnsRequest:
summary: With Add Ons
value: |-
goldEUR1ipaddresses21000video_streaming
SubscriptionWithAddOnsQuantityBasedRequest:
summary: With Quantity-Based Add Ons
value: |-
nowpothos550299150
SubscriptionWithAddOnsQuantityBasedPercentageRequest:
summary: With Quantity-Based Percentage Add Ons
value: |-
nowpothos10010.020.0
SubscriptionWithBillingInfoExistingRequest:
summary: With Existing Billing Info
value: |-
goldEUR1
SubscriptionWithBillingInfoNewRequest:
summary: With New Billing Info (And Account)
value: |-
goldEUR12verena@example.comVerenaExample4111-1111-1111-1111122019123 Main St.San FranciscoCA94105US
SubscriptionWithGiftCardRedemptionRequest:
summary: With Gift Card Redemption
value: |-
goldEUR1verena@example.comVerenaExample4111-1111-1111-1111122038123 Main St.San FranciscoCA94105USJHD776JENN99E6DD
SubscriptionWithGiftCardRedemptionCreateResponse:
summary: Creating With Gift Card Redemption
value: |-
goldGold planevenly37bfe445e10e91512fec6d491a9c3a53active4500EUR12016-08-03T15:50:09Z2016-08-03T15:50:10Z2016-08-03T15:50:09Z2016-09-03T15:50:09Ztrue2016-08-03T15:50:09Z394usstCA0.08750netautomatic
SubscriptionWithGiftCardRedemptionPreviewResponse:
summary: Previewing With Gift Card Redemption
value: |-
goldGold planVerena Example123 Main St.San FranciscoCA94105USevenly37bfe445e10e91512fec6d491a9c3a53active4500EUR12016-08-03T15:50:09Z2016-08-03T15:50:09Z2016-09-03T15:50:09Ztrue394usstCA0.08750netautomatic
SubscriptionWithShippingInfoRequest:
summary: With Shipping Info
value: |-
goldEUR1WorkVerenaExampleRecurly Inc555-222-1212verena@example.com123 Main St.Suite 101San FranciscoCA94105USfast_fast_fast999
SubscriptionWithCustomFieldsRequest:
summary: With Custom Fields
value: |-
goldEUR1device_idKIWTL-WER-ZXMRDpurchase_date2017-01-23
# shared request body definitions are great for endpoints
# that also have a /preview
requestBodies:
SubscriptionWithGiftCardRedemption:
required: true
content:
application/xml:
schema:
type: object
xml:
name: subscription
oneOf:
- $ref: "#/components/schemas/SubscriptionRequest"
- $ref: "#/components/schemas/SubscriptionRequestWithFeatures"
examples:
withNewAccount:
$ref: "#/components/examples/SubscriptionWithGiftCardRedemptionRequest"
# shared response body definitions are great for endpoints
# that also have an entry point elsewhere (e.g. /subscriptions and
# /accounts/:account_code/subscriptions). they are also great for
# common error responses.
responses:
PlanCreateUpdate:
description: ""
content:
application/xml:
schema:
$ref: "#/components/schemas/Plan"
examples:
fixedPricing:
$ref: "#/components/examples/PlanFixedPricingResponse"
rampPricing:
$ref: "#/components/examples/PlanRampPricingResponse"
revrec:
$ref: "#/components/examples/PlanWithRevRecResponse"
SubscriptionErrors422:
description: "Unprocessable Entity"
content:
application/xml:
schema:
$ref: "#/components/schemas/Errors"
examples:
invalidCoupon:
summary: Expired/Invalid Coupon
value: |-
is invalid
transactionError:
summary: When there's a transaction error
value: |-
declined_saveablegeneric_declinesoftThe transaction was declined without specific information. Please contact your payment gateway for more details or ask the customer to contact their bank.The transaction was declined. Please use a different card or contact your bank.The transaction was declined. Please use a different card or contact your bank.3c42a3ecc46a7aa602602e4033b9c2e6purchase5274424EURdeclinedcredit_card3383506subscriptionfalsetruefalsefalse127.0.0.1declined_saveablegeneric_declinesoftThe transaction was declined without specific information. Please contact your payment gateway for more details or ask the customer to contact their bank.The transaction was declined. Please use a different card or contact your bank.2017-03-15T21:21:16Z2017-03-15T21:21:16Z1VerenaExampleNew Company Nameverena@example.comVerenaExample123 Main St.San FranciscoCA94105USVisa2019124000000341
SubscriptionWithGiftCardRedemptionError400:
description: Already Redeemed
content:
application/xml:
schema:
allOf:
- $ref: "#/components/schemas/Error"
- properties:
symbol:
default: gift_card_already_redeemed
description:
default: This gift card has already been redeemed.
example: |-
gift_card_already_redeemedThis gift card has already been redeemed.
SubscriptionWithGiftCardRedemptionError404:
description: Wrong Redemption Code
content:
application/xml:
schema:
allOf:
- $ref: "#/components/schemas/Error404"
- properties:
description:
default: This gift card has already been redeemed.
example: |-
not_foundGift Card with redemption code JHD776JENN99E6DD not found