--- openapi: 3.0.0 info: title: Recurly V3 API description: | # Getting Started ## Versioning The V3 API is versioned to allow stability for integrators and flexibility for Recurly to continue making improvements. The versions follow a format that incorporates the approximate date the changes were released in a YYYY-MM-DD format, e.g. `v2021-02-25`. > *WARNING*: Specifying a version is required to get a successful response. Each request should specify a version using the `Accept` header: * `Accept: application/vnd.recurly.v2021-02-25` * `Accept: application/vnd.recurly.v2021-02-25+json` All responses will include a `Recurly-Version` header with the API version used to process the request: ``` Recurly-Version: recurly.v2021-02-25 ``` Recurly's client libraries correspond with API versions as listed below.
API Version Client Library Version
v2021-02-25 4.x
v2019-10-10 3.x
Client library releases: * [Node.js](https://github.com/recurly/recurly-client-node/releases) * [Python](https://github.com/recurly/recurly-client-python/releases) * [.NET](https://github.com/recurly/recurly-client-dotnet/releases) * [Ruby](https://github.com/recurly/recurly-client-ruby/releases) * [Java](https://github.com/recurly/recurly-client-java/releases) * [PHP](https://github.com/recurly/recurly-client-php/releases) * [Go](https://github.com/recurly/recurly-client-go/releases) Client libraries follow semantic versioning. For example, [Ruby client library version 3.18.1](https://github.com/recurly/recurly-client-ruby/releases/tag/3.18.1) represents major version `3`, minor version `18` with patch `1`. We encourage you to update to the latest version of the API and corresponding client library, as most recent versions are more performant than their predecessors. See the [changelog](https://developers.recurly.com/api/changelog.html) for a comprehensive list of changes introduced in the latest API version. ### Default Versions Specifying a version is required to get a successful response. If you wish to receive the latest version and are willing to accept the risk of breaking changes, you may specify a version of `latest`. The following media types will default the newest version of the API: * `application/vnd.recurly.latest` * `application/vnd.recurly.latest+json` ### Deprecation Responses for a deprecated version request will return two headers: ``` Recurly-Deprecated: TRUE Recurly-Sunset-Date: 2017-06-01T00:00:00+00:00 ``` The sunset date is an ISO-8601 formatted date time after which the version will no longer be accessible. ### Unsupported Versions A request for an unsupported version will return a status code of 406 and the body will include a list of supported versions: ``` { "error": { "type": "invalid_api_version", "message": "That accept header isn't in the format we use to specify an API version. Try one of these instead:", "acceptable_accept_headers": [ "application/vnd.recurly.v2016-03-01", "application/vnd.recurly.v2016-04-27", "application/vnd.recurly.v2016-07-27", "application/vnd.recurly.v2016-12-15", "application/vnd.recurly.v2017-01-12", "application/vnd.recurly.v2017-09-30", "application/vnd.recurly.v2018-01-24", "application/vnd.recurly.v2018-05-10", "application/vnd.recurly.v2018-06-06", "application/vnd.recurly.v2018-08-09", "application/vnd.recurly.v2019-10-10", "application/vnd.recurly.v2021-02-25" ] } } ``` ## Error Messages Error messages sent via the Recurly API are generally directed at developers and those who are familiar with API technology. When using the API and passing error messages to target systems, be mindful that these messages may not make sense in the context of the target system. Please consider changing these messages in the target system to be better suited to the audience of the system. Please see [transaction error codes](https://developers.recurly.com/pages/api-transaction-errors.html) for more details. ## Pagination ### Response Schema Every GET listing endpoint returns a response with the same schema: ``` { "object": "list", // Always "list" "has_more": true, // false if this is the last page of data "next": "https://...", // A URL pointing to the next page of data "data": [] // The data for this page as an array } ``` To page through every record, your code should continually call the URL at `next` until `has_more` is `false`. ### Query Parameters Most GET listing endpoints take query parameters that allow filtering and sorting the results. Some endpoints have additional parameters, which are documented on the respective endpoints, but most support the following parameters: * `ids`: A comma separated list of ids to match. * `limit`: The number of records to return per page. * `order`: The sort order of records. * `sort`: The date field to use in sorting. * `begin_time`: The start datetime to filter (ISO 8601). * `end_time`: The end datetime to filter (ISO 8601). ### Counting with HEAD Every GET listing endpoint also supports the HEAD HTTP method. Making a head request to the endpoint results in an empty body and an additional `Recurly-Total-Records` header. This is a count of the total number of records that the endpoint will return, taking into account the current filtering query parameters. ## 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 requests count towards the rate limit. Once your site moves into production mode, Recurly will only rate limit GET 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. If an API request exceeds the rate limit, the API will return a `429 Too Many Requests` HTTP status. If your business needs a higher limit, please contact support. The rate limit applied to your client can be determined with the `X-RateLimit-Limit` header, and the number of remaining requests is sent in the `X-RateLimit-Remaining` header. Finally, the `X-RateLimit-Reset` header contains an integer value representing the time, measured in seconds since the UNIX Epoch, at which the request count will be reset. ## Change Log A list of changes for this version can be found [in the changelog](https://developers.recurly.com/api/changelog.html#v2021-02-25---current-ga-version). version: v2021-02-25 security: - api_key: [] x-tagGroups: - name: Customers tags: - account - note - account_acquisition - billing_info - billing_infos - subscription - subscription_change - shipping_address - purchase - usage - automated_exports - name: Products and Promotions tags: - item - plan - add-on - measured_unit - coupon - coupon_redemption - unique_coupon_code - name: Invoices and Payments tags: - invoice - line_item - credit_payment - transaction - name: Configuration tags: - site - custom_field_definition - shipping_method - dunning_campaigns tags: - name: site x-displayName: Site - name: custom_field_definition x-displayName: Custom Field Definition description: Describes the fields that can use used as custom fields on accounts or subscriptions. - name: item x-displayName: Item description: |- For merchants who sell the same things to many customers, documenting those offerings in a catalog allows for faster charge creation, easier management of offerings, and analytics about your offerings across all sales channels. Because your offerings can be physical, digital, or service-oriented, Recurly collectively calls these offerings "Items". Recurly's item catalog requires the Credit Invoices and Subscription Billing Terms features to be enabled. - name: plan x-displayName: Plan description: A plan tells Recurly how often and how much to charge your customers. Plans can be created with free trials, optional products (called add-ons), setup fees, and more. - name: add-on x-displayName: Add-on description: An add-on is a charge billed each billing period in addition to a subscription’s base charge. Each plan may have one or more add-ons associated with it. - name: measured_unit x-displayName: Measured Unit description: A measured unit describes a usage-based add-on's usage. If different usage-based add-ons share the same measured unit, you can report on customer usage for those add-ons at the aggregated measured unit level. - name: account x-displayName: Account description: Accounts are core to managing your customers inside of Recurly. The account object stores the entire Recurly history of your customer and acts as the entry point for working with a customer's billing information, subscription data, transactions, invoices and more. - name: note x-displayName: Account Note description: Account notes allow your team to leave notes on an account to add context, e.g. the reason for a refund, customer requests, and/or complaints. These notes are internal and not exposed to your customers. - name: account_acquisition x-displayName: Account Acquisition Info description: Recurly offers the ability to record marketing data on customer accounts to match this data with revenue and billing data events in Recurly. - name: billing_info x-displayName: Billing Info description: Without the premium Wallet feature, an account can only have one stored payment method at a time. Examples include credit cards, PayPal, or bank accounts. Billing info is filled out by the customer upon purchase or when they update their information. - name: billing_infos x-displayName: Billing Infos description: If the premium Wallet feature is enabled, an account can have multiple payment methods stored. Examples include credit cards, PayPal, or bank accounts. Primary or backup billing infos can be designated from these endpoints. - name: subscription x-displayName: Subscription description: Subscriptions are created when your customers subscribe to one of your plans. The customer's subscription tells Recurly when and how much to bill the customer. - name: subscription_change x-displayName: Subscription Change description: Subscription changes alter subscription in a way that might affect the invoiced amount, such as changing the plan, add-ons, quantities, or shipping address. Changes can be made immediately in the current billing cycle or scheduled to take place at the next renewal. - name: shipping_address x-displayName: Shipping Address description: Shipping addresses are tied to a customer's account. Each account can have up to 20 different shipping addresses, and if you have enabled multiple subscriptions per account, you can associate different shipping addresses to each subscription. - name: invoice x-displayName: Invoice description: An invoice relates charges, credits, and payments together. When a subscription is created or renewed or a charge is created on the account, Recurly will sum the charges, discount or tax as appropriate, and send the invoice out for collection. - name: line_item x-displayName: Line Item description: Line items are the charges and credits on your customer's invoices. - name: credit_payment x-displayName: Credit Payment - name: purchase x-displayName: Purchase description: A purchase is a checkout containing at least one or more subscriptions or one-time charges (line items) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. - name: usage x-displayName: Usage description: Send Recurly your customer usage and we will automatically bill them in arrears at the end of the billing cycle. For more info on usage-based billing, [click here](https://docs.recurly.com/docs/usage-based-billing). - name: transaction x-displayName: Transaction description: Purchasing information is sent to your payment gateway in an action called a transaction. This includes the customer's billing information and the amount of money to be charged, voided, or refunded. - name: coupon x-displayName: Coupon description: Coupons can either be single codes that easily allow mass distribution by many customers or bulk coupons that can generate many unique coupons that can allow for individual delivery and tracking. - name: coupon_redemption x-displayName: Coupon Redemption description: Coupon redemptions are created when a coupon is applied to an account or subscription. This allows you to track your promotions. - name: unique_coupon_code x-displayName: Unique Coupon Code description: Unique coupon codes are generated from bulk coupons. - name: shipping_method x-displayName: Shipping Method description: Shipping methods offered to send products to customers. - name: automated_exports x-displayName: Automated Exports description: Automated exports of customer data. - name: dunning_campaigns x-displayName: Dunning Campaigns description: Settings used when attempting to dun customers whose payments are declined. paths: "/sites": get: operationId: list_sites summary: List sites description: | This route is most useful for finding a site's ID for subsequent requests. See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. tags: - site parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of sites. content: application/json: schema: "$ref": "#/components/schemas/SiteList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const sites = client.listSites({ params: { limit: 200 } }) for await (const site of sites.each()) { console.log(site.subdomain) } - lang: Python source: | params = {"limit": 200} sites = client.list_sites(params=params).items() for site in sites: print(site.subdomain) - lang: ".NET" source: | var optionalParams = new ListSitesParams() { Limit = 200 }; var sites = client.ListSites(optionalParams); foreach(Site site in sites) { Console.WriteLine(site.Subdomain); } - lang: Ruby source: | params = { limit: 200 } sites = @client.list_sites(params: params) sites.each do |site| puts "Site: #{site.subdomain}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager sites = client.listSites(params); for (Site site : sites) { System.out.println(site.getSubdomain()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $sites = $client->listSites($options); foreach($sites as $site) { echo 'Site: ' . $site->getSubdomain() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListSitesParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"asc\"),\n\tLimit: recurly.Int(200),\n}\n\nsites, err := client.ListSites(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor sites.HasMore() {\n\terr := sites.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, site := range sites.Data() {\n\t\tfmt.Printf(\"Site %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tsite.Id,\n\t\t\tsite.Subdomain,\n\t\t)\n\t}\n}" "/sites/{site_id}": get: operationId: get_site summary: Fetch a site tags: - site parameters: - "$ref": "#/components/parameters/site_id" responses: '200': description: A site. content: application/json: schema: "$ref": "#/components/schemas/Site" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const site = await client.getSite(siteId) console.log('Fetched site: ', site) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: site = client.get_site(site_id) print("Got Site %s" % site) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Site site = client.GetSite(siteId); Console.WriteLine($"Fetched site {site.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin site = @client.get_site(site_id: site_id) puts "Got Site #{site}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Site site = client.getSite(siteId); System.out.println("Fetched site: " + site.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $site = $client->getSite($site_id); echo 'Got Site:' . PHP_EOL; var_dump($site); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "site, err := client.GetSite(siteID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Site: %s\", site.Id)" "/accounts": get: tags: - account operationId: list_accounts summary: List a site's accounts description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_account_email" - "$ref": "#/components/parameters/filter_account_subscriber" - "$ref": "#/components/parameters/filter_account_past_due" responses: '200': description: A list of the site's accounts. content: application/json: schema: "$ref": "#/components/schemas/AccountList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const accounts = client.listAccounts({ params: { limit: 200 } }) for await (const account of accounts.each()) { console.log(account.code) } - lang: Python source: | params = {"limit": 200} accounts = client.list_accounts(params=params).items() for account in accounts: print(account.code) - lang: ".NET" source: | var optionalParams = new ListAccountsParams() { Limit = 200 }; var accounts = client.ListAccounts(optionalParams); foreach(Account account in accounts) { Console.WriteLine(account.Code); } - lang: Ruby source: | params = { limit: 200 } accounts = @client.list_accounts(params: params) accounts.each do |account| puts "Account: #{account.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time Pager accounts = client.listAccounts(params); for (Account acct : accounts) { System.out.println(acct.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $accounts = $client->listAccounts($options); foreach($accounts as $account) { echo 'Account code: ' . $account->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccounts, err := client.ListAccounts(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accounts.HasMore() {\n\terr := accounts.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, account := range accounts.Data() {\n\t\tfmt.Printf(\"Account %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\taccount.Id,\n\t\t\taccount.Code,\n\t\t)\n\t}\n}" post: tags: - account operationId: create_account summary: Create an account requestBody: content: application/json: schema: "$ref": "#/components/schemas/AccountCreate" required: true responses: '201': description: An account. content: application/json: schema: "$ref": "#/components/schemas/Account" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid parameters or an error running the billing info verification transaction. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const accountCreate = { code: accountCode, firstName: 'Benjamin', lastName: 'Du Monde', address: { street1: '900 Camp St', city: 'New Orleans', region: 'LA', postalCode: '70115', country: 'US' } } const account = await client.createAccount(accountCreate) console.log('Created Account: ', account.code) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: account_create = { "code": account_code, "first_name": "Benjamin", "last_name": "Du Monde", "acquisition": { "campaign": "podcast-marketing", "channel": "social_media", "subchannel": "twitter", "cost": {"currency": "USD", "amount": 0.50}, }, "shipping_addresses": [ { "nickname": "Home", "street1": "1 Tchoupitoulas St", "city": "New Orleans", "region": "LA", "country": "US", "postal_code": "70115", "first_name": "Aaron", "last_name": "Du Monde", } ], } account = client.create_account(account_create) print("Created Account %s" % account) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var accountReq = new AccountCreate() { Code = accountCode, FirstName = "Benjamin", LastName = "Du Monde", Address = new Address() { City = "New Orleans", Region = "LA", Country = "US", PostalCode = "70115", Street1 = "900 Camp St." } }; Account account = client.CreateAccount(accountReq); Console.WriteLine($"Created account {account.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin account_create = { code: account_code, first_name: "Benjamin", last_name: "Du Monde", acquisition: { campaign: "podcast-marketing", channel: "social_media", subchannel: "twitter", cost: { currency: "USD", amount: 0.50 } }, shipping_addresses: [ { nickname: "Home", street1: "1 Tchoupitoulas St", city: "New Orleans", region: "LA", country: "US", postal_code: "70115", first_name: "Benjamin", last_name: "Du Monde" } ] } account = @client.create_account(body: account_create) puts "Created Account #{account}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { AccountCreate accountReq = new AccountCreate(); Address address = new Address(); accountReq.setCode(accountCode); accountReq.setFirstName("Aaron"); accountReq.setLastName("Du Monde"); address.setStreet1("900 Camp St."); address.setCity("New Orleans"); address.setRegion("LA"); address.setCountry("US"); address.setPostalCode("70115"); accountReq.setAddress(address); Account account = client.createAccount(accountReq); System.out.println("Created account " + account.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $account_create = [ "code" => $account_code, "first_name" => "Douglas", "last_name" => "DuMonde", "shipping_addresses" => [ [ "first_name" => "Douglas", "last_name" => "DuMonde", "nickname" => "nola", "street1" => "1 Tchoupitoulas", "city" => "New Orleans", "postal_code" => "70130", "country" => "US" ] ] ]; $account = $client->createAccount($account_create); echo 'Created Account:' . PHP_EOL; var_dump($account); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "accountReq := &recurly.AccountCreate{\n\tCode: &accountCode,\n\tFirstName: recurly.String(\"Isaac\"),\n\tLastName: recurly.String(\"Du Monde\"),\n\tEmail: \ recurly.String(\"isaac@example.com\"),\n\tBillingInfo: &recurly.BillingInfoCreate{\n\t\tFirstName: recurly.String(\"Isaac\"),\n\t\tLastName: recurly.String(\"Du Monde\"),\n\t\tAddress: &recurly.AddressCreate{\n\t\t\tPhone: recurly.String(\"415-555-5555\"),\n\t\t\tStreet1: \ recurly.String(\"400 Alabama St.\"),\n\t\t\tCity: recurly.String(\"San Francisco\"),\n\t\t\tPostalCode: recurly.String(\"94110\"),\n\t\t\tCountry: \ recurly.String(\"US\"),\n\t\t\tRegion: recurly.String(\"CA\"),\n\t\t},\n\t\tNumber: recurly.String(\"4111111111111111\"),\n\t\tMonth: recurly.String(\"12\"),\n\t\tYear: \ recurly.String(\"22\"),\n\t\tCvv: recurly.String(\"123\"),\n\t},\n}\n\naccount, err := client.CreateAccount(accountReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Account: %s\", account.Id)" "/accounts/{account_id}": parameters: - "$ref": "#/components/parameters/account_id" get: tags: - account operationId: get_account summary: Fetch an account responses: '200': description: An account. content: application/json: schema: "$ref": "#/components/schemas/Account" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const account = await client.getAccount(accountId) console.log('Fetched account: ', account.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: account = client.get_account(account_id) print("Got Account %s" % account) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Account account = client.GetAccount(accountId); Console.WriteLine($"Fetched account {account.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin account = @client.get_account(account_id: account_id) puts "Got Account #{account}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Account account = client.getAccount(accountId); System.out.println("Fetched account: " + account.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $account = $client->getAccount($account_id); echo 'Got Account:' . PHP_EOL; var_dump($account); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "account, err := client.GetAccount(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Println(\"Fetched Account \", account.Id)" put: tags: - account operationId: update_account summary: Update an account requestBody: content: application/json: schema: "$ref": "#/components/schemas/AccountUpdate" required: true responses: '200': description: An account. content: application/json: schema: "$ref": "#/components/schemas/Account" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid parameters or an error running the billing info verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const accountUpdate = { firstName: 'Aaron', lastName: 'Du Monde' } const account = await client.updateAccount(accountId, accountUpdate) console.log('Updated account: ', account) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: account_update = {"first_name": "Aaron", "last_name": "Du Monde"} account = client.update_account(account_id, account_update) print("Updated Account %s" % account) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var accountReq = new AccountUpdate() { FirstName = "Aaron", LastName = "Du Monde" }; Account account = client.UpdateAccount(accountId, accountReq); Console.WriteLine(account.FirstName); Console.WriteLine(account.LastName); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin account_update = { first_name: "Aaron", last_name: "Du Monde", } account = @client.update_account( account_id: account_id, body: account_update ) puts "Updated Account #{account}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final AccountUpdate accountUpdate = new AccountUpdate(); accountUpdate.setFirstName("Aaron"); accountUpdate.setLastName("Du Monde"); final Account account = client.updateAccount(accountId, accountUpdate); System.out.println("Updated account: " + account.getCode()); System.out.println(account.getFirstName()); System.out.println(account.getLastName()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $account_update = [ "first_name" => "Douglas", "last_name" => "Du Monde", ]; $account = $client->updateAccount($account_id, $account_update); echo 'Updated Account:' . PHP_EOL; var_dump($account); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.AccountUpdate{\n\tFirstName: recurly.String(\"Joanna\"),\n\tLastName: \ recurly.String(\"DuMonde\"),\n}\naccount, err := client.UpdateAccount(accountID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Account: %s\", account.Id)" delete: tags: - account operationId: deactivate_account summary: Deactivate an account description: Deactivating 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). We recommend closing accounts only when all business is concluded with a customer. responses: '200': description: An account. content: application/json: schema: "$ref": "#/components/schemas/Account" '422': description: Account may already be inactive. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const account = await client.deactivateAccount(accountId) console.log('Deleted account: ', account.code) } catch (err) { if (err && err.type === 'not-found') { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it throw err } - lang: Python source: | try: account = client.deactivate_account(account_id) print("Deactivated Account %s" % account) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Account account = client.DeactivateAccount(accountId); Console.WriteLine($"Deactivated account {account.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin account = @client.deactivate_account(account_id: account_id) puts "Deactivated Account #{account}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { Account account = client.deactivateAccount(accountId); System.out.println("deactivated account " + account.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $account = $client->deactivateAccount($account_id); echo 'Deactivated Account:' . PHP_EOL; var_dump($account); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "account, err := client.DeactivateAccount(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Deactivated Account: %s\", account.Id)" "/accounts/{account_id}/acquisition": parameters: - "$ref": "#/components/parameters/account_id" get: tags: - account_acquisition operationId: get_account_acquisition summary: Fetch an account's acquisition data responses: '200': description: An account's acquisition data. content: application/json: schema: "$ref": "#/components/schemas/AccountAcquisition" '404': description: Account has no acquisition data, or incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const acquisition = await client.getAccountAcquisition(accountId) console.log('Fetched account acquisition: ', acquisition.id) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: acquisition = client.get_account_acquisition(account_id) print("Got AccountAcquisition %s" % acquisition) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AccountAcquisition acquisition = client.GetAccountAcquisition(accountId); Console.WriteLine($"Fetched account acquisition {acquisition.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.get_account_acquisition(account_id: account_id) puts "Got AccountAcquisition" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final AccountAcquisition acquisition = client.getAccountAcquisition(accountId); System.out.println("Fetched account acquisition " + acquisition.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $acquisition = $client->getAccountAcquisition($account_id); echo 'Got Account Acquisition:' . PHP_EOL; var_dump($acquisition); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "accountAcq, err := client.GetAccountAcquisition(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Account Acquisition: %v\", accountAcq.Id)" put: tags: - account_acquisition operationId: update_account_acquisition summary: Update an account's acquisition data requestBody: content: application/json: schema: "$ref": "#/components/schemas/AccountAcquisitionUpdate" required: true responses: '200': description: An account's updated acquisition data. content: application/json: schema: "$ref": "#/components/schemas/AccountAcquisition" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const acquisitionUpdate = { campaign: "big-event-campaign", channel: "social_media", subchannel: "twitter" } const accountAcquisition = await client.updateAccountAcquisition(accountId, acquisitionUpdate) console.log('Edited Account Acquisition: ', accountAcquisition) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: acquisition_update = { "campaign": "podcast-marketing", "channel": "social_media", "subchannel": "twitter", "cost": {"currency": "USD", "amount": 0.50}, } acquisition = client.update_account_acquisition(account_id, acquisition_update) print("Updated AccountAcquisition %s" % acquisition) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var acquisitionReq = new AccountAcquisitionUpdate() { Campaign = "big-event-campaign", Channel = Channel.SocialMedia, Subchannel = "twitter" }; AccountAcquisition accountAcquisition = client.UpdateAccountAcquisition(accountId, acquisitionReq); Console.WriteLine(accountAcquisition); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin acquisition_update = { campaign: "podcast-marketing", channel: "social_media", subchannel: "twitter", cost: { currency: "USD", amount: 0.50 } } acquisition = @client.update_account_acquisition( account_id: account_id, body: acquisition_update ) puts "Updated AccountAcqusition #{acquisition}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final AccountAcquisitionUpdate acqUpdate = new AccountAcquisitionUpdate(); acqUpdate.setCampaign("big-event-campaign"); acqUpdate.setChannel(Constants.Channel.SOCIAL_MEDIA); acqUpdate.setSubchannel("twitter"); final AccountAcquisition accountAcquisition = client.updateAccountAcquisition(accountId, acqUpdate); System.out.println(accountAcquisition); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $acquisition_update = [ "campaign" => "big-event-campaign", "channel" => "social_media", "subchannel" => "twitter" ]; $acquisition = $client->updateAccountAcquisition($account_id, $acquisition_update); echo 'Updated AccountAcquisition:' . PHP_EOL; var_dump($acquisition); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.AccountAcquisitionUpdate{\n\tCampaign: recurly.String(\"big-event-campaign\"),\n\tChannel: \ recurly.String(\"social_media\"),\n\tSubchannel: recurly.String(\"twitter\"),\n}\naccount, err := client.UpdateAccountAcquisition(accountID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Account Acquisition: %s\", account.Id)" delete: tags: - account_acquisition operationId: remove_account_acquisition summary: Remove an account's acquisition data responses: '204': description: Acquisition data was succesfully deleted. '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { await client.removeAccountAcquisition(accountId) console.log('Removed account acquisition from account: ', accountId) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_account_acquisition(account_id) print("Removed AccountAcquisition for Account id=%s" % account_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { client.RemoveAccountAcquisition(accountId); Console.WriteLine($"Removed account acquisition from account {accountId}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin acquisition = @client.remove_account_acquisition(account_id: account_id) puts "Removed AccountAcqusition #{acquisition}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { client.removeAccountAcquisition(accountId); System.out.println("Removed account acquisition from account " + accountId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $client->removeAccountAcquisition($account_id); echo "Removed Account Acquisition:" . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "client.RemoveAccountAcquisition(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Removed Account Acquisition: %s\", accountAcquisition.Id)" "/accounts/{account_id}/reactivate": parameters: - "$ref": "#/components/parameters/account_id" put: tags: - account operationId: reactivate_account summary: Reactivate an inactive account description: Reactivating an account will restore its history but the customer will need to provide new billing information to continue billing. responses: '200': description: An account. content: application/json: schema: "$ref": "#/components/schemas/Account" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Account is already active. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const account = await client.reactivateAccount(accountId) console.log('Reactivated account: ', account.code) } catch (err) { if (err && err.type === 'not_found') { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it throw err } - lang: Python source: | try: account = client.reactivate_account(account_id) print("Reactivated Account %s" % account) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Account account = client.ReactivateAccount(accountId); Console.WriteLine($"Reactivated account {account.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin account = @client.reactivate_account(account_id: account_id) puts "Reactivated account #{account}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Account account = client.reactivateAccount(accountId); System.out.println("Reactivated account: " + account.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $account = $client->reactivateAccount($account_id); echo 'Reactivated Account:' . PHP_EOL; var_dump($account); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "account, err := client.ReactivateAccount(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Reactivated Account: %s\", account.Id)" "/accounts/{account_id}/balance": parameters: - "$ref": "#/components/parameters/account_id" get: tags: - account operationId: get_account_balance summary: Fetch an account's balance and past due status responses: '200': description: An account's balance. content: application/json: schema: "$ref": "#/components/schemas/AccountBalance" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const balance = await client.getAccountBalance(accountId) console.log('Fetched account balance: ', balance.balances) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: balance = client.get_account_balance(account_id) print("Got AccountBalance %s" % balance) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AccountBalance balance = client.GetAccountBalance(accountId); Console.WriteLine($"Fetched account balance {balance.Balances}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin balance = @client.get_account_balance(account_id: account_id) puts "Got AccountBalance #{balance}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final AccountBalance balance = client.getAccountBalance(accountId); System.out.println("Fetched account balance " + balance.getBalances()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $balance = $client->getAccountBalance($account_id); echo 'Got Account Balance:' . PHP_EOL; var_dump($balance); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "accountBalance, err := client.GetAccountBalance(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Account Balance: %v\", accountBalance)" "/accounts/{account_id}/billing_info": get: tags: - billing_info operationId: get_billing_info summary: Fetch an account's billing information parameters: - "$ref": "#/components/parameters/account_id" responses: '200': description: An account's billing information. content: application/json: schema: "$ref": "#/components/schemas/BillingInfo" '404': description: Account has no billing information, or incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const billingInfo = await client.getBillingInfo(accountId) console.log('Fetched Billing Info: ', billingInfo.id) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: binfo = client.get_billing_info(account_id) print("Got BillingInfo %s" % binfo) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { BillingInfo billingInfo = client.GetBillingInfo(accountId); Console.WriteLine($"Fetched billing info {billingInfo.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin billing = @client.get_billing_info(account_id: account_id) puts "Got BillingInfo #{billing}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final BillingInfo billingInfo = client.getBillingInfo(accountId); System.out.println("Fetched billing info " + billingInfo.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $binfo = $client->getBillingInfo($account_id); echo 'Got BillingInfo:' . PHP_EOL; var_dump($binfo); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "billingInfo, err := client.GetBillingInfo(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Billing Info: %v\", billingInfo)" put: tags: - billing_info operationId: update_billing_info summary: Set an account's billing information description: | If you're using Recurly.js to securely submit data from webforms without sending it through your server, you can associate the billing information with an account by passing in the `token_id`. The only other fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`. For credit card payments you'll need the following required fields: - first_name - last_name - number - month - year For external (not Recurly.js) tokenized payments you'll need the following required fields: - first_name - last_name - gateway_token - gateway_code parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/BillingInfoCreate" required: true responses: '200': description: Updated billing information. content: application/json: schema: "$ref": "#/components/schemas/BillingInfo" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid billing information, or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" x-code-samples: - lang: Node.js source: | try { const billingInfoUpdate = { firstName: 'Aaron', lastName: 'Du Monde', } const billingInfo = await client.updateBillingInfo(accountId, billingInfoUpdate) console.log('Updated billing info: ', billingInfo.id) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: billing_update = {"first_name": "Aaron", "last_name": "Du Monde"} billing = client.update_billing_info(account_id, billing_update) print("Updated BillingInfo %s" % billing) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var billingReq = new BillingInfoCreate() { FirstName = "Benjamin", LastName = "Du Monde" }; BillingInfo billingInfo = client.UpdateBillingInfo(accountId, billingReq); Console.WriteLine($"Updated billing info {billingInfo.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin billing_update = { first_name: "Aaron", last_name: "Du Monde", } billing = @client.update_billing_info( account_id: account_id, body: billing_update ) puts "Updated BillingInfo #{billing}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final BillingInfoCreate billingUpdate = new BillingInfoCreate(); billingUpdate.setFirstName("Aaron"); billingUpdate.setLastName("Du Monde"); final BillingInfo billingInfo = client.updateBillingInfo(accountId, billingUpdate); System.out.println("Updated billing info " + billingInfo.getId()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $binfo_update = [ "first_name" => "Douglas", "last_name" => "Du Monde", ]; $binfo = $client->updateBillingInfo($account_id, $binfo_update); echo 'Updated BillingInfo:' . PHP_EOL; var_dump($binfo); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.BillingInfoCreate{\n\tFirstName: recurly.String(\"Joanna\"),\n\tLastName: \ recurly.String(\"DuMonde\"),\n}\nbillingInfo, err := client.UpdateBillingInfo(accountID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Billing Info: %s\", billingInfo)" delete: tags: - billing_info operationId: remove_billing_info summary: Remove an account's billing information parameters: - "$ref": "#/components/parameters/account_id" description: You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into dunning unless the billing information is updated before the renewal occurs. responses: '204': description: Billing information deleted '404': description: Account has no billing information, or incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { client.removeBillingInfo(accountId) console.log('Removed billing info from account: ', accountId) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_billing_info(account_id) print("Removed BillingInfo for Account id=%s" % account_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { client.RemoveBillingInfo(accountId); Console.WriteLine($"Removed billing info from account {accountId}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.remove_billing_info(account_id: account_id) puts "Removed BillingInfo #{account_id}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { client.removeBillingInfo(accountId); System.out.println("Removed billing info from account " + accountId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $client->removeBillingInfo($account_id); echo "Removed Billing Info: " . $account_id . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "billingInfo, err := client.RemoveBillingInfo(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Billing Info: %v\", billingInfo)" "/accounts/{account_id}/billing_info/verify": post: tags: - billing_info operationId: verify_billing_info summary: Verify an account's credit card billing information parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/BillingInfoVerify" required: false responses: '200': description: Transaction information from verify. content: application/json: schema: "$ref": "#/components/schemas/Transaction" '404': description: Account has no billing information, or incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid billing information, or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" x-code-samples: - lang: Node.js source: | try { const transaction = await client.verifyBillingInfo(accountId) console.log('Fetched Transaction: ', transaction.id) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: transaction = client.verify_billing_info(account_id) print("Got Transaction %s" % transaction) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Transaction transaction = client.VerifyBillingInfo(accountId); Console.WriteLine($"Fetched transaction {transaction.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin transaction = @client.verify_billing_info(account_id: account_id) puts "Got Transaction #{transaction}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Transaction transaction = client.verifyBillingInfo(accountId); System.out.println("Fetched transaction " + transaction.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $transaction = $client->verifyBillingInfo($account_id); echo 'Got Transaction:' . PHP_EOL; var_dump($transaction); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "verifyBillingInfoParams := &recurly.VerifyBillingInfoParams{}\ntransaction, err := client.VerifyBillingInfo(accountID, verifyBillingInfoParams)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Transaction: %v\", transaction)" "/accounts/{account_id}/billing_infos": get: tags: - billing_infos operationId: list_billing_infos summary: Get the list of billing information associated with an account description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the the billing information for an account's content: application/json: schema: "$ref": "#/components/schemas/BillingInfoList" '400': description: Invalid or unpermitted parameter content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] post: tags: - billing_infos operationId: create_billing_info summary: Add new billing information on an account description: | If you're using Recurly.js to securely submit data from webforms without sending it through your server, you can associate the billing information with an account by passing in the `token_id`. The only other fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`. For credit card payments you'll need the following required fields: - first_name - last_name - number - month - year For external (not Recurly.js) tokenized payments you'll need the following required fields: - first_name - last_name - gateway_token - gateway_code parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/BillingInfoCreate" required: true responses: '200': description: Updated billing information. content: application/json: schema: "$ref": "#/components/schemas/BillingInfo" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid billing information, or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" x-code-samples: [] "/accounts/{account_id}/billing_infos/{billing_info_id}": get: tags: - billing_infos operationId: get_a_billing_info summary: Fetch a billing info parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/billing_info_id" responses: '200': description: A billing info. content: application/json: schema: "$ref": "#/components/schemas/BillingInfo" '404': description: Incorrect site, account, or billing info ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] put: tags: - billing_infos operationId: update_a_billing_info summary: Update an account's billing information description: | If you're using Recurly.js to securely submit data from webforms without sending it through your server, you can associate the billing information with an account by passing in the `token_id`. The only other fields permitted with `token_id` are `primary_payment_method` and/or `backup_payment_method`. For credit card payments you'll need the following required fields: - first_name - last_name - number - month - year For external (not Recurly.js) tokenized payments you'll need the following required fields: - first_name - last_name - gateway_token - gateway_code parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/billing_info_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/BillingInfoCreate" required: true responses: '200': description: Updated billing information. content: application/json: schema: "$ref": "#/components/schemas/BillingInfo" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid billing information, or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" x-code-samples: [] delete: tags: - billing_infos operationId: remove_a_billing_info summary: Remove an account's billing information parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/billing_info_id" description: You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into dunning unless the billing information is updated before the renewal occurs. responses: '204': description: Billing information deleted '404': description: Account has no billing information, or incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Billing info cannot be deleted. Please set a new primary billing info before deleting this billing info content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/accounts/{account_id}/coupon_redemptions": get: tags: - coupon_redemption operationId: list_account_coupon_redemptions summary: Show the coupon redemptions for an account description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of the the coupon redemptions on an account. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemptionList" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const redemptions = client.listAccountCouponRedemptions(accountId, { params: { limit: 200 } }) for await (const redemption of redemptions.each()) { console.log(redemption.id) } - lang: Python source: | params = {"limit": 200} redemptions = client.list_account_coupon_redemptions(account_id, params=params).items() for redemption in redemptions: print(redemption.id) - lang: ".NET" source: | var redemptions = client.ListAccountCouponRedemptions(accountId); foreach(CouponRedemption redemption in redemptions) { Console.WriteLine(redemption.Id); } - lang: Ruby source: | params = { limit: 200 } redemptions = @client.list_account_coupon_redemptions( account_id: account_id, params: params ) redemptions.each do |redemption| puts "CouponRedemption: #{redemption.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager redemptions = client.listAccountCouponRedemptions(accountId, params); for (CouponRedemption redemption : redemptions) { System.out.println(redemption.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_coupon_redemptions = $client->listAccountCouponRedemptions($account->getId(), $options); foreach($account_coupon_redemptions as $coupon_redemption) { echo 'Coupon redemption: ' . $coupon_redemption->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountCouponRedemptionsParams{\n\tSort: recurly.String(\"created_at\"),\n}\naccountCouponRedemptions, err := client.ListAccountCouponRedemptions(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountCouponRedemptions.HasMore() {\n\terr := accountCouponRedemptions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, couponRedemption := range accountCouponRedemptions.Data() {\n\t\tfmt.Printf(\"Account Coupon Redemption %3d: %s\\n\",\n\t\t\ti,\n\t\t\tcouponRedemption.Id,\n\t\t)\n\t}\n}" "/accounts/{account_id}/coupon_redemptions/active": get: tags: - coupon_redemption operationId: list_active_coupon_redemptions summary: Show the coupon redemptions that are active on an account description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" responses: '200': description: Active coupon redemptions on an account. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemptionList" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const redemptions = await client.listActiveCouponRedemptions(accountId, { params: { limit: 200 } }) for await (const redemption of redemptions.each()) { console.log('Fetched coupon redemption: ', redemption.id) } - lang: Python source: | params = {"limit": 200} redemptions = client.list_active_coupon_redemptions(account_id, params=params).items() for redemption in redemptions: print(redemption.id) - lang: ".NET" source: | try { var redemptions = client.ListActiveCouponRedemptions(accountId); foreach(CouponRedemption redemption in redemptions) { Console.WriteLine($"Fetched coupon redemption {redemption.Id}"); } } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | params = { limit: 200 } redemptions = @client.list_active_coupon_redemptions(account_id: account_id, params: params) redemptions.each do |redemption| puts "Redemption: #{redemption.id}" end - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $redemptions = $client->listActiveCouponRedemptions($account_id, $options); foreach($redemptions as $redemption) { echo 'Got Redemption: ' . $redemption->getId() . PHP_EOL; } post: tags: - coupon_redemption operationId: create_coupon_redemption summary: Generate an active coupon redemption on an account or subscription parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/CouponRedemptionCreate" required: true responses: '200': description: Returns the new coupon redemption. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemption" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Python source: | try: redemption_create = {"currency": "USD", "coupon_id": coupon_id} redemption = client.create_coupon_redemption(account_id, redemption_create) print("Created Redemption %s" % redemption) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: |- try { var redemptionReq = new CouponRedemptionCreate() { CouponId = couponId, }; var redemption = client.CreateCouponRedemption(accountId, redemptionReq); Console.WriteLine($"Created coupon redemption: {redemption.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin redemption_create = { currency: 'USD', coupon_id: coupon_id } redemption = @client.create_coupon_redemption( account_id: account_id, body: redemption_create ) puts "Created CouponRedemption #{redemption}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { CouponRedemptionCreate coupRedCreate = new CouponRedemptionCreate(); coupRedCreate.setCouponId(couponId); CouponRedemption redemption = client.createCouponRedemption(accountId, coupRedCreate); System.out.println("Created coupon redemption " + redemption.getId()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $redemption_create = [ "currency" => "USD", "coupon_id" => "code-$coupon_code" ]; $redemption = $client->createCouponRedemption($account_id, $redemption_create); echo "Created Redemption:" . PHP_EOL; var_dump($redemption); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "redemptionReq := &recurly.CouponRedemptionCreate{\n\tCouponId: recurly.String(couponID),\n\tCurrency: recurly.String(\"USD\"),\n}\n\ncouponRedemption, err := client.CreateCouponRedemption(accountID, redemptionReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Coupon Redemption: %v\", couponRedemption)" delete: tags: - coupon_redemption operationId: remove_coupon_redemption summary: Delete the active coupon redemption from an account parameters: - "$ref": "#/components/parameters/account_id" responses: '200': description: Coupon redemption deleted. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemption" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const redemption = await client.removeCouponRedemption(accountId) console.log('Removed coupon redemption: ', redemption.id) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_coupon_redemption(account_id) print("Removed Redemption from Account id=%s" % account_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: |- try { var redemption = client.RemoveCouponRedemption(accountId); Console.WriteLine($"Removed coupon redemption from account: {redemption.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.remove_coupon_redemption(account_id: account_id) puts "Removed CouponRedemption #{account_id}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final CouponRedemption redemption = client.removeCouponRedemption(accountId); System.out.println("Removed coupon redemption " + redemption.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $redemption = $client->removeCouponRedemption($account_id); echo "Removed Active Coupon Redemption:" . PHP_EOL; var_dump($redemption); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "couponRedemption, err := client.RemoveCouponRedemption(accountID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Coupon Redemption: %v\", couponRedemption.Id)" "/accounts/{account_id}/credit_payments": get: tags: - credit_payment operationId: list_account_credit_payments summary: List an account's credit payments description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the account's credit payments. content: application/json: schema: "$ref": "#/components/schemas/CreditPaymentList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const payments = client.listAccountCreditPayments(accountId, { params: { limit: 200 } }) for await (const payment of payments.each()) { console.log(payment.uuid) } - lang: Python source: | params = {"limit": 200} payments = client.list_account_credit_payments(account_id, params=params).items() for payment in payments: print(payment.id) - lang: ".NET" source: | var optionalParams = new ListAccountCreditPaymentsParams() { Limit = 200 }; var payments = client.ListAccountCreditPayments(accountId, optionalParams); foreach(CreditPayment payment in payments) { Console.WriteLine(payment.Uuid); } - lang: Ruby source: | params = { limit: 200 } payments = @client.list_account_credit_payments( account_id: account_id, params: params ) payments.each do |payment| puts "CreditPayment: #{payment.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time Pager payments = client.listAccountCreditPayments(accountId, params); for (CreditPayment payment : payments) { System.out.println(payment.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $credit_payments = $client->listAccountCreditPayments($account->getId(), $options); foreach($credit_payments as $payment) { echo 'Credit Payment: ' . $payment->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountCreditPaymentsParams{\n\tSort: \ recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncreditPayments, err := client.ListAccountCreditPayments(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor creditPayments.HasMore() {\n\terr := creditPayments.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, creditPayment := range creditPayments.Data() {\n\t\tfmt.Printf(\"Account Credit Payment %3d: %s\\n\",\n\t\t\ti,\n\t\t\tcreditPayment.Id,\n\t\t)\n\t}\n}" "/accounts/{account_id}/invoices": get: tags: - invoice operationId: list_account_invoices summary: List an account's invoices description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_invoice_type" responses: '200': description: A list of the account's invoices. content: application/json: schema: "$ref": "#/components/schemas/InvoiceList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const invoices = client.listAccountInvoices(accountId, { params: { limit: 200 } }) for await (const invoice of invoices.each()) { console.log(invoice.number) } - lang: Python source: | params = {"limit": 200} invoices = client.list_account_invoices(account_id, params=params).items() for invoice in invoices: print(invoice.number) - lang: ".NET" source: | var invoices = client.ListAccountInvoices(accountId); foreach(Invoice invoice in invoices) { Console.WriteLine(invoice.Id); } - lang: Ruby source: | params = { limit: 200 } invoices = @client.list_account_invoices( account_id: account_id, params: params ) invoices.each do |invoice| puts "Invoice: #{invoice.number}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager invoices = client.listAccountInvoices(accountId, params); for (Invoice invoice : invoices) { System.out.println(invoice.getNumber()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $invoices = $client->listAccountInvoices($account->getId(), $options); foreach($invoices as $invoice) { echo 'Account invoice: ' . $invoice->getNumber() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountInvoicesParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccountInvoices, err := client.ListAccountInvoices(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountInvoices.HasMore() {\n\terr := accountInvoices.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, invoice := range accountInvoices.Data() {\n\t\tfmt.Printf(\"Account Invoice %3d: %s\\n\",\n\t\t\ti,\n\t\t\tinvoice.Id,\n\t\t)\n\t}\n}" post: tags: - invoice operationId: create_invoice summary: Create an invoice for pending line items parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/InvoiceCreate" required: true responses: '201': description: Returns the new invoices. content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollection" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid parameters, no pending line items, or error running the transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let invoiceCreate = { currency: 'USD', collectionMethod: 'automatic' } let invoiceCollection = await client.createInvoice(accountId, invoiceCreate) console.log('Created Invoice') console.log('Charge Invoice: ', invoiceCollection.chargeInvoice) console.log('Credit Invoices: ', invoiceCollection.creditInvoices) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice_create = {"currency": "USD", "collection_method": "automatic"} invoice_collection = client.create_invoice(account_id, invoice_create) print("Created InvoiceCollection %s" % invoice_collection) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { // creates an invoice based on pending charges or credits on account var collection = client.CreateInvoice(accountId, new InvoiceCreate() { Currency = "USD", CollectionMethod = CollectionMethod.Automatic }); Console.WriteLine("Created Invoice"); Console.WriteLine(collection.ChargeInvoice); Console.WriteLine(collection.CreditInvoices); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice_create = { currency: 'USD', collection_method: 'automatic' } collection = @client.create_invoice( account_id: account_id, body: invoice_create ) puts "Created InvoiceCollection #{collection}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { InvoiceCreate invoiceCreate = new InvoiceCreate(); invoiceCreate.setCurrency("USD"); invoiceCreate.setCollectionMethod(Constants.CollectionMethod.AUTOMATIC); InvoiceCollection collection = client.createInvoice(accountId, invoiceCreate); System.out.println("Created Invoice"); System.out.println(collection.getChargeInvoice()); System.out.println(collection.getCreditInvoices()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $invoice_create = [ "currency" => "USD", "collection_method" => "automatic" ]; $invoice_collection = $client->createInvoice( $account_id, $invoice_create ); echo "Created Invoice:" . PHP_EOL; var_dump($invoice_collection); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "invoiceReq := &recurly.InvoiceCreate{\n\tCurrency: recurly.String(\"USD\"),\n\tCollectionMethod: recurly.String(\"automatic\"),\n}\n\ncollection, err := client.CreateInvoice(accountID, invoiceReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Invoice Collection: %v\", collection)" "/accounts/{account_id}/invoices/preview": post: tags: - invoice operationId: preview_invoice summary: Preview new invoice for pending line items parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/InvoiceCreate" required: true responses: '200': description: Returns the invoice previews. content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollection" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid parameter or pending line items. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const collection = await client.previewInvoice(accountId, { currency: "USD", collectionMethod: "automatic" }) console.log(`Previewed invoice due at ${collection.chargeInvoice.dueAt}`) console.log(collection.chargeInvoice) console.log(collection.creditInvoices) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice_preview = {"currency": "USD", "collection_method": "automatic"} invoice_collection = client.preview_invoice(account_id, invoice_preview) print("Preview InvoiceCollection %s" % invoice_collection) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { // creates a preview invoice based on pending charges or credits on account var collection = client.PreviewInvoice(accountId, new InvoiceCreate() { Currency = "USD", CollectionMethod = CollectionMethod.Automatic }); Console.WriteLine($"Previewed invoice DueAt {collection.ChargeInvoice.DueAt}"); Console.WriteLine(collection.ChargeInvoice); Console.WriteLine(collection.CreditInvoices); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice_preview = { currency: "USD", collection_method: "automatic" } collection = @client.create_invoice( account_id: account_id, body: invoice_preview ) puts "Created InvoiceCollection #{collection}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { InvoiceCreate invoiceCreate = new InvoiceCreate(); invoiceCreate.setCurrency("USD"); invoiceCreate.setCollectionMethod(Constants.CollectionMethod.AUTOMATIC); InvoiceCollection collection = client.previewInvoice(accountId, invoiceCreate); System.out.println("Previewed Invoice due at " + collection.getChargeInvoice().getDueAt()); System.out.println(collection.getChargeInvoice()); System.out.println(collection.getCreditInvoices()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $invoice_preview = [ "currency" => "USD", "collection_method" => "automatic" ]; $invoice_collection = $client->previewInvoice( $account_id, $invoice_preview ); echo "Previewed Invoice:" . PHP_EOL; var_dump($invoice_collection); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "invoiceReq := &recurly.InvoiceCreate{\n\tCurrency: recurly.String(\"USD\"),\n}\n\ncollection, err := client.PreviewInvoice(accountID, invoiceReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Preview Invoice %v\", collection.ChargeInvoice)" "/accounts/{account_id}/line_items": get: tags: - line_item operationId: list_account_line_items summary: List an account's line items description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_line_item_original" - "$ref": "#/components/parameters/filter_line_item_state" - "$ref": "#/components/parameters/filter_line_item_type" responses: '200': description: A list of the account's line items. content: application/json: schema: "$ref": "#/components/schemas/LineItemList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const lineItems = client.listAccountLineItems(accountId, { params: { limit: 200 } }) for await (const lineItem of lineItems.each()) { console.log(lineItem.id) } - lang: Python source: | params = {"limit": 200} line_items = client.list_account_line_items(account_id, params=params).items() for line_item in line_items: print(line_item.id) - lang: ".NET" source: | var lineItems = client.ListAccountLineItems(accountId); foreach(LineItem lineItem in lineItems) { Console.WriteLine(lineItem.Id); } - lang: Ruby source: | params = { limit: 200 } line_items = @client.list_account_line_items( account_id: account_id, params: params ) line_items.each do |line_item| puts "LineItem: #{line_item.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager lineItems = client.listAccountLineItems(accountId, params); for (LineItem lineItem : lineItems) { System.out.println(lineItem.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_line_items = $client->listAccountLineItems($account_id, $options); foreach($account_line_items as $line_item) { echo 'Account line item: ' . $line_item->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountLineItemsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccountLineItems, err := client.ListAccountLineItems(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountLineItems.HasMore() {\n\terr := accountLineItems.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, lineItem := range accountLineItems.Data() {\n\t\tfmt.Printf(\"Account Line Item %3d: %s\\n\",\n\t\t\ti,\n\t\t\tlineItem.Id,\n\t\t)\n\t}\n}" post: tags: - line_item operationId: create_line_item summary: Create a new line item for the account parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/LineItemCreate" required: true responses: '201': description: Returns the new line item. content: application/json: schema: "$ref": "#/components/schemas/LineItem" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let lineItemReq = { currency: 'USD', unitAmount: 1000, type: 'charge' // choose "credit" for a credit } let lineItem = await client.createLineItem(accountId, lineItemReq) console.log('Created Line Item: ', lineItem.uuid) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: line_item_create = { "currency": "USD", "unit_amount": 1000, "type": "charge", # choose "credit" for a credit } line_item = client.create_line_item(account_id, line_item_create) print("Created LineItem %s" % line_item) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { // creates a pending charge or credit on the account var lineItemReq = new LineItemCreate() { Currency = "USD", UnitAmount = 1000, Type = LineItemType.Charge // choose "credit" for a credit }; LineItem lineItem = client.CreateLineItem(accountId, lineItemReq); Console.WriteLine($"Created line item {lineItem.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin line_item_create = { currency: 'USD', unit_amount: 1_000, type: :charge } line_item = @client.create_line_item( account_id: account_id, body: line_item_create ) puts "Created LineItem #{line_item}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { LineItemCreate lineItemCreate = new LineItemCreate(); lineItemCreate.setCurrency("USD"); lineItemCreate.setUnitAmount(new BigDecimal("1000.0")); lineItemCreate.setType(Constants.LineItemType.CHARGE); // choose "credit" for a credit LineItem lineItem = client.createLineItem(accountId, lineItemCreate); System.out.println("Created line item " + lineItem.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $line_item_create = [ 'currency' => 'USD', 'unit_amount' => 1000, 'type' => 'charge' ]; $line_item = $client->createLineItem( $account->getId(), $line_item_create ); echo 'Created Line Item:' . PHP_EOL; var_dump($line_item); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "lineItemReq := &recurly.LineItemCreate{\n\tCurrency: recurly.String(\"USD\"),\n\tUnitAmount: recurly.Float(1000),\n\tType: recurly.String(\"charge\"),\n}\n\nlineItem, err := client.CreateLineItem(accountID, lineItemReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Line Item: %v\", lineItem)" "/accounts/{account_id}/notes": get: tags: - note operationId: list_account_notes summary: Fetch a list of an account's notes description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" responses: '200': description: A list of an account's notes. content: application/json: schema: "$ref": "#/components/schemas/AccountNoteList" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const notes = client.listAccountNotes(accountId, { params: { limit: 200 } }) for await (const note of notes.each()) { console.log(note.message) } - lang: Python source: | params = {"limit": 200} line_items = client.list_account_line_items(account_id, params=params).items() for line_item in line_items: print(line_item.id) - lang: ".NET" source: | var notes = client.ListAccountNotes(accountId); foreach(AccountNote note in notes) { Console.WriteLine(note.Message); } - lang: Ruby source: | params = { limit: 200 } account_notes = @client.list_account_notes(account_id: account_id, params: params) account_notes.each do |note| puts "AccountNote: #{note.message}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager notes = client.listAccountNotes(accountId, params); for (AccountNote note : notes) { System.out.println(note.getMessage()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_notes = $client->listAccountNotes($account_id, $options); foreach($account_notes as $note) { echo 'Account note: ' . $note->getMessage() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountNotesParams{}\naccountNotes, err := client.ListAccountNotes(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountNotes.HasMore() {\n\terr := accountNotes.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, note := range accountNotes.Data() {\n\t\tfmt.Printf(\"Account Note %3d: %s\\n\",\n\t\t\ti,\n\t\t\tnote.Id,\n\t\t)\n\t}\n}" "/accounts/{account_id}/notes/{account_note_id}": get: tags: - note operationId: get_account_note summary: Fetch an account note parameters: - "$ref": "#/components/parameters/account_id" - name: account_note_id in: path description: Account Note ID. required: true schema: type: string responses: '200': description: An account note. content: application/json: schema: "$ref": "#/components/schemas/AccountNote" '404': description: Incorrect site, account or note ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { console.log(accountId) const note = await client.getAccountNote(accountId, accountNoteId) console.log('Fetched account note: ', note.message) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: note = client.get_account_note(account_id, note_id) print("Got AccountNote %s" % note) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AccountNote note = client.GetAccountNote(accountId, accountNoteId); Console.WriteLine($"Fetched account note: {note.Message}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin note = @client.get_account_note( account_id: account_id, account_note_id: note_id ) puts "Got AccountNote #{note}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final AccountNote note = client.getAccountNote(accountId, accountNoteId); System.out.println("Fetched account note: " + note.getMessage()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $note = $client->getAccountNote($account_id, $account_node_id); echo 'Got Account Note:' . PHP_EOL; var_dump($note); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "accountNote, err := client.GetAccountNote(accountID, accountNoteID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Account Note: %v\", accountNote)" "/accounts/{account_id}/shipping_addresses": get: tags: - shipping_address operationId: list_shipping_addresses summary: Fetch a list of an account's shipping addresses description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of an account's shipping addresses. content: application/json: schema: "$ref": "#/components/schemas/ShippingAddressList" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const addresses = client.listShippingAddresses(accountId, { params: { limit: 200 } }) for await (const address of addresses.each()) { console.log(address.street1) } - lang: Python source: | shipping_addresses = client.list_shipping_addresses(account_id).items() for shipping_address in shipping_addresses: print(shipping_address.id) - lang: ".NET" source: | var addresses = client.ListShippingAddresses(accountId); foreach(ShippingAddress address in addresses) { Console.WriteLine(address.Street1); } - lang: Ruby source: | params = { limit: 200 } shipping_addresses = @client.list_shipping_addresses( account_id: account_id, params: params ) shipping_addresses.each do |addr| puts "ShippingAddress: #{addr.nickname} - #{addr.street1}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager addresses = client.listShippingAddresses(accountId, params); for (ShippingAddress address : addresses) { System.out.println(address.getStreet1()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $shippingAddresses = $client->listShippingAddresses($account_id, $options); foreach($shippingAddresses as $address) { echo 'Shipping Address: ' . $address->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListShippingAddressesParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nshippingAddresses, err := client.ListShippingAddresses(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor shippingAddresses.HasMore() {\n\terr := shippingAddresses.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, shippingAddress := range shippingAddresses.Data() {\n\t\tfmt.Printf(\"Shipping Address %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tshippingAddress.Id,\n\t\t\tshippingAddress.Street1,\n\t\t)\n\t}\n}" post: tags: - shipping_address operationId: create_shipping_address summary: Create a new shipping address for the account parameters: - "$ref": "#/components/parameters/account_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/ShippingAddressCreate" required: true responses: '200': description: Returns the new shipping address. content: application/json: schema: "$ref": "#/components/schemas/ShippingAddress" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const shippingAddressCreate = { firstName: 'Aaron', lastName: 'Du Monde', street1: '900 Camp St.', city: 'New Orleans', region: 'LA', postalCode: '70115', country: 'US' } const address = await client.createShippingAddress(accountId, shippingAddressCreate) console.log('Created shipping address: ', address.street1) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: shipping_addr_create = { "first_name": "Aaron", "last_name": "Du Monde", "street1": "900 Camp St.", "city": "New Orleans", "postal_code": "70115", "country": "US", } shad = client.create_shipping_address(account_id, shipping_addr_create) print("Created ShippingAddress %s" % shad) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var addrReq = new ShippingAddressCreate() { FirstName = "Benjamin", LastName = "Du Monde", Street1 = "900 Camp St.", City = "New Orleans", Region = "LA", PostalCode = "70115", Country = "US", }; ShippingAddress address = client.CreateShippingAddress(accountId, addrReq); Console.WriteLine($"Created shipping address {address.Street1}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin shipping_address_create = { nickname: 'Work', street1: '900 Camp St', city: 'New Orleans', region: 'LA', country: 'US', postal_code: '70115', first_name: 'Joanna', last_name: 'Du Monde' } shipping_address = @client.create_shipping_address(account_id: account_id, body: shipping_address_create) puts "Created Shipping Address #{shipping_address}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { ShippingAddressCreate shippingAddressCreate = new ShippingAddressCreate(); shippingAddressCreate.setFirstName("Aaron"); shippingAddressCreate.setLastName("Du Monde"); shippingAddressCreate.setStreet1("900 Camp St"); shippingAddressCreate.setCity("New Orleans"); shippingAddressCreate.setRegion("LA"); shippingAddressCreate.setPostalCode("70115"); shippingAddressCreate.setCountry("US"); ShippingAddress shippingAddress = client.createShippingAddress(accountId, shippingAddressCreate); System.out.println("Created shipping address " + shippingAddress.getStreet1()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $address_create = [ "nickname" => "Work", "street1" => "900 Camp St", "city" => "New Orleans", "region" => "LA", "country" => "US", "postal_code" => "70115", "first_name" => "Douglas", "last_name" => "Du Monde" ]; $shipping_address = $client->createShippingAddress($account_id, $address_create); echo "Created Shpping Address:" . PHP_EOL; var_dump($shipping_address); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don"t know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "shippingReq := &recurly.ShippingAddressCreate{\n\tNickname: recurly.String(\"Home\"),\n\tStreet1: \ recurly.String(\"1 Tchoupitoulas St\"),\n\tCity: recurly.String(\"New Orleans\"),\n\tRegion: recurly.String(\"LA\"),\n\tCountry: recurly.String(\"US\"),\n\tPostalCode: recurly.String(\"70115\"),\n\tFirstName: recurly.String(\"Aaron\"),\n\tLastName: \ recurly.String(\"Du Monde\"),\n}\n\nshippingAddress, err := client.CreateShippingAddress(accountID, shippingReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Shipping Address: %v\", shippingAddress.Id)" "/accounts/{account_id}/shipping_addresses/{shipping_address_id}": get: tags: - shipping_address operationId: get_shipping_address summary: Fetch an account's shipping address parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/shipping_address_id" responses: '200': description: A shipping address. content: application/json: schema: "$ref": "#/components/schemas/ShippingAddress" '404': description: Incorrect site, account, or shipping address ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const address = await client.getShippingAddress(accountId, shippingAddressId) console.log('Fetched shipping address: ', address.street1) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.get_shipping_address(account_id, shipping_address_id) print("Got ShippingAddress %s" % shipping_address_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { ShippingAddress address = client.GetShippingAddress(accountId, shippingAddressId); Console.WriteLine($"Fetched shipping address {address.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin address = @client.get_shipping_address( account_id: account_id, shipping_address_id: shipping_address_id ) puts "Got ShippingAddress #{address}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final ShippingAddress address = client.getShippingAddress(accountId, shippingAddressId); System.out.println("Fetched shipping address " + address.getId()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $shipping_address = $client->getShippingAddress($account_id, $shipping_address_id); echo 'Got Shipping Address:' . PHP_EOL; var_dump($shipping_address); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "shippingAddress, err := client.GetShippingAddress(accountID, shippingAddressID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Shipping Address: %v\", shippingAddress)" put: tags: - shipping_address operationId: update_shipping_address summary: Update an account's shipping address parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/shipping_address_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/ShippingAddressUpdate" required: true responses: '200': description: The updated shipping address. content: application/json: schema: "$ref": "#/components/schemas/ShippingAddress" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site, account, or shipping address ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const shadUpdate = { firstName: "Benjamin", lastName: "Du Monde" } const address = await client.updateShippingAddress(accountId, shippingAddressId, shadUpdate) console.log('Updated shipping address: ', address.street1) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: address_update = { "first_name": "Aaron", "last_name": "Du Monde", "postal_code": "70130", } address = client.update_shipping_address( account_id, shipping_address_id, address_update ) print("Updated ShippingAddress %s" % address) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var shadReq = new ShippingAddressUpdate() { FirstName = "Aaron", LastName = "Du Monde" }; ShippingAddress address = client.UpdateShippingAddress(accountId, shippingAddressId, shadReq); Console.WriteLine($"Updated shipping address {address.Street1}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin address_update = { first_name: "Aaron", last_name: "Du Monde", postal_code: "70130" } address = @client.update_shipping_address( account_id: account_id, shipping_address_id: shipping_address_id, body: address_update ) puts "Updated ShippingAddress #{address}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final ShippingAddressUpdate shadUpdate = new ShippingAddressUpdate(); shadUpdate.setFirstName("Aaron"); shadUpdate.setLastName("Du Monde"); final ShippingAddress address = client.updateShippingAddress(accountId, shippingAddressId, shadUpdate); System.out.println("Updated shipping address " + address.getStreet1()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $shad_update = [ "first_name" => "Douglas", "last_name" => "Du Monde", ]; $shad = $client->updateShippingAddress($account_id, $shipping_address_id, $shad_update); echo 'Updated Shipping Address:' . PHP_EOL; var_dump($shad); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.ShippingAddressUpdate{\n\tFirstName: recurly.String(\"Joanna\"),\n\tLastName: \ recurly.String(\"DuMonde\"),\n}\nshippingAddress, err := client.UpdateShippingAddress(accountID, shippingAddressID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Shipping Address: %v\", shippingAddress)" delete: tags: - shipping_address operationId: remove_shipping_address summary: Remove an account's shipping address parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/shipping_address_id" responses: '204': description: Shipping address deleted. '404': description: Incorrect site, account, or shipping address ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { await client.removeShippingAddress(accountId, shippingAddress.id) console.log('Removed shipping address: ', shippingAddress.street1) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_shipping_address(account_id, shipping_address_id) print("Removed ShippingAddress %s" % shipping_address_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { client.RemoveShippingAddress(accountId, shippingAddressId); Console.WriteLine($"Removed shipping address {shippingAddressId}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.remove_shipping_address( account_id: account_id, shipping_address_id: shipping_address_id ) puts "Removed ShippingAddress #{shipping_address_id}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { client.removeShippingAddress(accountId, shippingAddressId); System.out.println("Removed shipping address " + shippingAddressId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: |- try { $client->removeShippingAddress($account_id, $shipping_address_id); echo "Removed Shipping Address:" . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "shippingAddress, err := client.RemoveShippingAddress(accountID, shippingAddressID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Shipping Address: %v\", shippingAddress)" "/accounts/{account_id}/subscriptions": get: tags: - subscription operationId: list_account_subscriptions summary: List an account's subscriptions description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_subscription_state" responses: '200': description: A list of the account's subscriptions. content: application/json: schema: "$ref": "#/components/schemas/SubscriptionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const subscriptions = client.listAccountSubscriptions(accountId, { params: { limit: 200 } }) for await (const subscription of subscriptions.each()) { console.log(subscription.uuid) } - lang: Python source: | params = {"limit": 200} subscriptions = client.list_account_subscriptions(account.id, params=params).items() for subscription in subscriptions: print(subscription.uuid) - lang: ".NET" source: | var subscriptions = client.ListAccountSubscriptions(accountId); foreach(Subscription subscription in subscriptions) { Console.WriteLine(subscription.Id); } - lang: Ruby source: | params = { limit: 200 } subscriptions = @client.list_account_subscriptions( account_id: account_id, params: params ) subscriptions.each do |subscription| puts "Subscription: #{subscription.uuid}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager subscriptions = client.listAccountSubscriptions(accountId, params); for (Subscription subscription : subscriptions) { System.out.println(subscription.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_subscriptions = $client->listAccountSubscriptions($account_id, $options); foreach($account_subscriptions as $sub) { echo 'Account subscription: ' . $sub->getUuid() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountSubscriptionsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccountSubscriptions, err := client.ListAccountSubscriptions(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountSubscriptions.HasMore() {\n\terr := accountSubscriptions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, sub := range accountSubscriptions.Data() {\n\t\tfmt.Printf(\"Account Subscription %3d: %s\\n\",\n\t\t\ti,\n\t\t\tsub.Id,\n\t\t)\n\t}\n}" "/accounts/{account_id}/transactions": get: tags: - transaction operationId: list_account_transactions summary: List an account's transactions description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_transaction_type" - "$ref": "#/components/parameters/filter_transaction_success" responses: '200': description: A list of the account's transactions. content: application/json: schema: "$ref": "#/components/schemas/TransactionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const transactions = client.listAccountTransactions(accountId, { params: { limit: 200 } }) for await (const transaction of transactions.each()) { console.log(transaction.uuid) } - lang: Python source: | params = {"limit": 200} transactions = client.list_account_transactions(account_id, params=params).items() for transaction in transactions: print("Transaction %s" % transaction.id) - lang: ".NET" source: | var transactions = client.ListAccountTransactions(accountId); foreach(Transaction transaction in transactions) { Console.WriteLine(transaction.Id); } - lang: Ruby source: | params = { limit: 200 } transactions = @client.list_account_transactions( account_id: account_id, params: params ) transactions.each do |transaction| puts "Transaction: #{transaction.uuid}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager transactions = client.listAccountTransactions(accountId, params); for (Transaction transaction : transactions) { System.out.println(transaction.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_transactions = $client->listAccountTransactions($account_id, $options); foreach($account_transactions as $transaction) { echo 'Account transactions: ' . $transaction->getUuid() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountTransactionsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccountTransactions, err := client.ListAccountTransactions(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountTransactions.HasMore() {\n\terr := accountTransactions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, transaction := range accountTransactions.Data() {\n\t\tfmt.Printf(\"Account Transaction %3d: %s\\n\",\n\t\t\ti,\n\t\t\ttransaction.Id,\n\t\t)\n\t}\n}" "/accounts/{account_id}/accounts": get: tags: - account operationId: list_child_accounts summary: List an account's child accounts description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/account_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_account_email" - "$ref": "#/components/parameters/filter_account_subscriber" - "$ref": "#/components/parameters/filter_account_past_due" responses: '200': description: A list of an account's child accounts. content: application/json: schema: "$ref": "#/components/schemas/AccountList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Python source: | params = {"limit": 200} child_accounts = client.list_child_accounts(account_id, params=params).items() for account in child_accounts: print("Child Account %s" % account.code) - lang: Ruby source: | params = { limit: 200 } child_accounts = @client.list_child_accounts( account_id: account_id, params: params ) child_accounts.each do |child| puts "Account: #{child.code}" end - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $child_accounts = $client->listChildAccounts($account_id, $options); foreach($child_accounts as $child_account) { echo 'Child Account: ' . $child_account->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListChildAccountsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naccounts, err := client.ListChildAccounts(accountID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accounts.HasMore() {\n\terr := accounts.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, account := range accounts.Data() {\n\t\tfmt.Printf(\"Child Account %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\taccount.Id,\n\t\t\taccount.Code,\n\t\t)\n\t}\n}" "/acquisitions": get: tags: - account_acquisition operationId: list_account_acquisition summary: List a site's account acquisition data description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the site's account acquisition data. content: application/json: schema: "$ref": "#/components/schemas/AccountAcquisitionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const acquisitions = client.listAccountAcquisition({ params: { limit: 200 } }) for await (const acquisition of acquisitions.each()) { console.log(acquisition.id) } - lang: Python source: | params = {"limit": 200} acquisitions = client.list_account_acquisition(params=params).items() for acquisition in acquisitions: print(acquisition.id) - lang: ".NET" source: | var acquisitions = client.ListAccountAcquisition(); foreach(AccountAcquisition acquisition in acquisitions) { Console.WriteLine(acquisition.Id); } - lang: Ruby source: | params = { limit: 200 } acquisitions = @client.list_account_acquisition(params: params) acquisitions.each do |acquisition| puts "AccountAcquisition: #{acquisition.cost}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager acquisitions = client.listAccountAcquisition(params); for (AccountAcquisition acquisition : acquisitions) { System.out.println(acquisition.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $account_acquisition = $client->listAccountAcquisition($options); foreach($account_acquisition as $aa) { echo 'Account acquisition: ' . $aa->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAccountAcquisitionParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"asc\"),\n\tLimit: recurly.Int(200),\n}\naccountAcquisition, err := client.ListAccountAcquisition(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor accountAcquisition.HasMore() {\n\terr := accountAcquisition.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, a := range accountAcquisition.Data() {\n\t\tfmt.Printf(\"Account Acquisition %3d: %s\\n\",\n\t\t\ti,\n\t\t\ta.Id,\n\t\t)\n\t}\n}" "/coupons": get: tags: - coupon operationId: list_coupons summary: List a site's coupons description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the site's coupons. content: application/json: schema: "$ref": "#/components/schemas/CouponList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const coupons = client.listCoupons({ params: { limit: 200 } }) for await (const coupon of coupons.each()) { console.log(coupon.code) } - lang: Python source: | params = {"limit": 200} coupons = client.list_coupons(params=params).items() for coupon in coupons: print(coupon.code) - lang: ".NET" source: | var optionalParams = new ListCouponsParams() { Limit = 200 }; var coupons = client.ListCoupons(optionalParams); foreach(Coupon coupon in coupons) { Console.WriteLine(coupon.Code); } - lang: Ruby source: | params = { limit: 200 } coupons = @client.list_coupons(params: params) coupons.each do |coupon| puts "coupon: #{coupon.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager coupons = client.listCoupons(params); for (Coupon coupon : coupons) { System.out.println(coupon.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $coupons = $client->listCoupons($options); foreach($coupons as $coupon) { echo 'Coupon: ' . $coupon->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListCouponsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncoupons, err := client.ListCoupons(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor coupons.HasMore() {\n\terr := coupons.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, coupon := range coupons.Data() {\n\t\tfmt.Printf(\"Coupon %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tcoupon.Id,\n\t\t\tcoupon.Code,\n\t\t)\n\t}\n}" post: tags: - coupon operationId: create_coupon summary: Create a new coupon requestBody: content: application/json: schema: "$ref": "#/components/schemas/CouponCreate" required: true responses: '201': description: A new coupon. content: application/json: schema: "$ref": "#/components/schemas/Coupon" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const couponCreate = { name: "Promotional Coupon", code: couponCode, discount_type: "fixed", currencies: [{"currency": "USD", "discount": 10}], } const coupon = await client.createCoupon(couponCreate) console.log('Created coupon: ', coupon.id) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: coupon_create = { "name": "Promotional Coupon", "code": coupon_code, "discount_type": "fixed", "currencies": [{"currency": "USD", "discount": 10000}], } coupon = client.create_coupon(coupon_create) print("Created Coupon %s" % coupon) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var couponReq = new CouponCreate() { Name = "Promotional Coupon", Code = couponCode, DiscountType = DiscountType.Fixed, Currencies = new List() { new CouponPricing() { Currency = "USD", Discount = 1000 } } }; Coupon coupon = client.CreateCoupon(couponReq); Console.WriteLine($"Created coupon {coupon.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin coupon_create = { name: "Promotional Coupon", code: coupon_code, discount_type: 'fixed', currencies: [ { currency: 'USD', discount: 10_000 } ] } coupon = @client.create_coupon( body: coupon_create ) puts "Created Coupon #{coupon}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { CouponCreate couponCreate = new CouponCreate(); couponCreate.setName("Promotional Coupon"); couponCreate.setCode(couponCode); List currencies = new ArrayList(); CouponPricing couponPrice = new CouponPricing(); couponPrice.setCurrency("USD"); couponPrice.setDiscount(new BigDecimal("10.0")); currencies.add(couponPrice); couponCreate.setCurrencies(currencies); couponCreate.setDiscountType(Constants.DiscountType.FIXED); Coupon coupon = client.createCoupon(couponCreate); System.out.println("Created coupon " + coupon.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $coupon_create = [ "name" => "Promotional Coupon", "code" => $coupon_code, "discount_type" => "fixed", "currencies" => [ "currency" => "USD", "discount" => 10 ] ]; $coupon = $client->createCoupon($coupon_create); echo 'Created Coupon:' . PHP_EOL; var_dump($coupon); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "couponReq := &recurly.CouponCreate{\n\tName: recurly.String(\"Promotional Coupon\"),\n\tMaxRedemptions: recurly.Int(50),\n\tMaxRedemptionsPerAccount: recurly.Int(1),\n\tCode: recurly.String(genUuid()),\n\tDiscountType: \ recurly.String(\"percent\"),\n\tDiscountPercent: recurly.Int(25),\n}\n\ncoupon, err := client.CreateCoupon(couponReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Coupon: %v\", coupon.Id)" "/coupons/{coupon_id}": get: tags: - coupon operationId: get_coupon summary: Fetch a coupon parameters: - "$ref": "#/components/parameters/coupon_id" responses: '200': description: A coupon. content: application/json: schema: "$ref": "#/components/schemas/Coupon" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const coupon = await client.getCoupon(couponId) console.log('Fetched coupon: ', coupon.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: coupon = client.get_coupon(coupon_id) print("Got Coupon %s" % coupon) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Coupon coupon = client.GetCoupon(couponId); Console.WriteLine($"Fetched coupon {coupon.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin coupon = @client.get_coupon(coupon_id: coupon_id) puts "Got Coupon #{coupon}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Coupon coupon = client.getCoupon(couponId); System.out.println("Fetched coupon " + coupon.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $coupon = $client->getCoupon($coupon_id); echo 'Got Coupon:' . PHP_EOL; var_dump($coupon); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "coupon, err := client.GetCoupon(couponID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Coupon: %v\", coupon.Id)" put: tags: - coupon operationId: update_coupon summary: Update an active coupon parameters: - "$ref": "#/components/parameters/coupon_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/CouponUpdate" required: true responses: '200': description: The updated coupon. content: application/json: schema: "$ref": "#/components/schemas/Coupon" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const couponUpdate = { name: "New Coupon Name" } const coupon = await client.updateCoupon(couponId, couponUpdate) console.log('Updated coupon: ', coupon) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: coupon_update = { "name": "New Coupon Name", } coupon = client.update_coupon(coupon_id, coupon_update) print("Updated Coupon %s" % coupon) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { var couponReq = new CouponUpdate() { Name = "New Coupon Name" }; Coupon coupon = client.UpdateCoupon(couponId, couponReq); Console.WriteLine($"Updated Coupon: {coupon.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin coupon_update = { name: "New Coupon Name" } coupon = @client.update_coupon(coupon_id: coupon_id, body: coupon_update) puts "Updated Coupon #{coupon}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final CouponUpdate couponUpdate = new CouponUpdate(); couponUpdate.setName("New Coupon Name"); final Coupon coupon = client.updateCoupon(couponId, couponUpdate); System.out.println("Updated coupon: " + coupon.getCode()); System.out.println(coupon.getName()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $coupon_update = [ "name" => "New Coupon Name" ]; $coupon = $client->updateCoupon($coupon_id, $coupon_update); echo 'Updated Coupon:' . PHP_EOL; var_dump($coupon); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.CouponUpdate{\n\tName: recurly.String(\"New Coupon Name\"),\n}\ncoupon, err := client.UpdateCoupon(couponID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Updated Coupon: %v\", coupon.Id)" delete: tags: - coupon operationId: deactivate_coupon summary: Expire a coupon parameters: - "$ref": "#/components/parameters/coupon_id" description: Mark an existing Coupon as expired responses: '200': description: The expired Coupon content: application/json: schema: "$ref": "#/components/schemas/Coupon" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const coupon = await client.deactivateCoupon(couponId) console.log('Deactivated coupon: ', coupon.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: coupon = client.deactivate_coupon(coupon_id) print("Deactivated Coupon %s" % coupon) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Coupon coupon = client.DeactivateCoupon(couponId); Console.WriteLine($"Deactivated coupon {coupon.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin coupon = @client.deactivate_coupon(coupon_id: coupon_id) puts "Deactivated Coupon #{coupon}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Coupon coupon = client.deactivateCoupon(couponId); System.out.println("Deactivated coupon " + coupon.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $coupon = $client->deactivateCoupon($coupon_id); echo 'Deactivated Coupon:' . PHP_EOL; var_dump($coupon); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } "/coupons/{coupon_id}/generate": post: tags: - unique_coupon_code operationId: generate_unique_coupon_codes summary: Generate unique coupon codes parameters: - "$ref": "#/components/parameters/coupon_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/CouponBulkCreate" required: true responses: '201': description: | A set of parameters that can be passed to the `list_unique_coupon_codes` endpoint to obtain only the newly generated `UniqueCouponCodes`. content: application/json: schema: "$ref": "#/components/schemas/UniqueCouponCodeParams" '400': description: Invalid or unpermitted parameter; perhaps you tried to generate more than 200 codes at a time? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/coupons/{coupon_id}/restore": put: tags: - coupon operationId: restore_coupon summary: Restore an inactive coupon description: Make an expired coupon redeemable again. You can change editable fields in this call. parameters: - "$ref": "#/components/parameters/coupon_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/CouponUpdate" required: true responses: '200': description: The restored coupon. content: application/json: schema: "$ref": "#/components/schemas/Coupon" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/coupons/{coupon_id}/unique_coupon_codes": get: tags: - unique_coupon_code operationId: list_unique_coupon_codes summary: List unique coupon codes associated with a bulk coupon description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/coupon_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of unique coupon codes that were generated content: application/json: schema: "$ref": "#/components/schemas/UniqueCouponCodeList" '404': description: Incorrect site or coupon ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/credit_payments": get: tags: - credit_payment operationId: list_credit_payments summary: List a site's credit payments description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the site's credit payments. content: application/json: schema: "$ref": "#/components/schemas/CreditPaymentList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or account ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const payments = client.listCreditPayments({ params: { limit: 200 } }) for await (const payment of payments.each()) { console.log(payment.uuid) } - lang: Python source: | params = {"limit": 200} payments = client.list_credit_payments(params=params).items() for payment in payments: print("Credit Payment %s" % payment.id) - lang: ".NET" source: | var optionalParams = new ListCreditPaymentsParams() { Limit = 200 }; var payments = client.ListCreditPayments(optionalParams); foreach(CreditPayment payment in payments) { Console.WriteLine(payment.Uuid); } - lang: Ruby source: | params = { limit: 200 } payments = @client.list_credit_payments(params: params) payments.each do |payment| puts "CreditPayment: #{payment.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager payments = client.listCreditPayments(params); for (CreditPayment payment : payments) { System.out.println(payment.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $credit_payments = $client->listCreditPayments($options); foreach($credit_payments as $payment) { echo 'Credit Payment: ' . $payment->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListCreditPaymentsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncreditPayments, err := client.ListCreditPayments(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor creditPayments.HasMore() {\n\terr := creditPayments.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, creditPayment := range creditPayments.Data() {\n\t\tfmt.Printf(\"Credit Payment %3d: %s\\n\",\n\t\t\ti,\n\t\t\tcreditPayment.Id,\n\t\t)\n\t}\n}" "/credit_payments/{credit_payment_id}": get: tags: - credit_payment operationId: get_credit_payment summary: Fetch a credit payment parameters: - "$ref": "#/components/parameters/credit_payment_id" responses: '200': description: A credit payment. content: application/json: schema: "$ref": "#/components/schemas/CreditPayment" '404': description: Incorrect site or credit payment ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/custom_field_definitions": get: tags: - custom_field_definition operationId: list_custom_field_definitions summary: List a site's custom field definitions description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - name: related_type in: query description: Filter by related type. schema: "$ref": "#/components/schemas/RelatedTypeEnum" responses: '200': description: A list of the site's custom field definitions. content: application/json: schema: "$ref": "#/components/schemas/CustomFieldDefinitionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const definitions = client.listCustomFieldDefinitions({ params: { limit: 200 } }) for await (const definition of definitions.each()) { console.log(definition.displayName) } - lang: Python source: | params = {"limit": 200} custom_fields = client.list_custom_field_definitions(params=params).items() for custom_field in custom_fields: print(custom_field.name) - lang: ".NET" source: | var optionalParams = new ListCustomFieldDefinitionsParams() { Limit = 200 }; var fields = client.ListCustomFieldDefinitions(optionalParams); foreach(CustomFieldDefinition def in fields) { Console.WriteLine(def.DisplayName); } - lang: Ruby source: | params = { limit: 200 } custom_fields = @client.list_custom_field_definitions(params: params) custom_fields.each do |field| puts "CustomFieldDefinition: #{field.name}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager fields = client.listCustomFieldDefinitions(params); for (CustomFieldDefinition field : fields) { System.out.println(field.getDisplayName()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $custom_field_definitions = $client->listCustomFieldDefinitions($options); foreach($custom_field_definitions as $definition) { echo 'Custom Field Definition: ' . $definition->getName() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListCustomFieldDefinitionsParams{\n\tSort: \ recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ncustomFieldDefinitions, err := client.ListCustomFieldDefinitions(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor customFieldDefinitions.HasMore() {\n\terr := customFieldDefinitions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, definition := range customFieldDefinitions.Data() {\n\t\tfmt.Printf(\"Custom Field Definition %3d: %s\\n\",\n\t\t\ti,\n\t\t\tdefinition.Id,\n\t\t)\n\t}\n}" "/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: An custom field definition. content: application/json: schema: "$ref": "#/components/schemas/CustomFieldDefinition" '404': description: Incorrect site or custom field definition ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const definition = await client.getCustomFieldDefinition(definitionId) console.log('Fetched custom field definition: ', definition.displayName) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: custom_field_definition = client.get_custom_field_definition(custom_field_definition_id) print("Custom Field Definition %s" % custom_field_definition) except recurly.errors.NotFoundError as e: print("Invoice not found") - lang: ".NET" source: | try { CustomFieldDefinition definition = client.GetCustomFieldDefinition(definitionId); Console.WriteLine($"Fetched custom field definition {definition.DisplayName}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin custom_field_definition = @client.get_custom_field_definition( custom_field_definition_id: custom_field_definition_id ) puts "Got Custom Field Definition #{custom_field_definition}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final CustomFieldDefinition definition = client.getCustomFieldDefinition(definitionId); System.out.println("Fetched custom field definition " + definition.getDisplayName()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $custom_field_def = $client->getCustomFieldDefinition($definition_id); echo 'Got CustomFieldDefinition:' . PHP_EOL; var_dump($custom_field_def); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "definition, err := client.GetCustomFieldDefinition(customFieldDefinitionID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Custom Field Definition: %s\", definition.Id)" "/items": get: tags: - item operationId: list_items summary: List a site's items description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of the site's items. content: application/json: schema: "$ref": "#/components/schemas/ItemList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const items = client.listItems({ params: { limit: 200 } }) for await (const item of items.each()) { console.log(item.code) } - lang: Python source: | params = {"limit": 200} items = client.list_items(params=params).items() for item in items: print(item.code) - lang: ".NET" source: | var optionalParams = new ListItemsParams() { Limit = 200 }; var items = client.ListItems(optionalParams); foreach(Item item in items) { Console.WriteLine(item.Code); } - lang: Ruby source: | params = { limit: 200 } items = @client.list_items(params: params) items.each do |item| puts "Item: #{item.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time Pager items = client.listItems(params); for (Item item : items) { System.out.println(item.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $items = $client->listItems($options); foreach($items as $item) { echo 'Item: ' . $item->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListItemsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nitems, err := client.ListItems(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor items.HasMore() {\n\terr := items.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, item := range items.Data() {\n\t\tfmt.Printf(\"Item %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\titem.Id,\n\t\t\titem.Code,\n\t\t)\n\t}\n}" post: tags: - item operationId: create_item summary: Create a new item requestBody: content: application/json: schema: "$ref": "#/components/schemas/ItemCreate" required: true responses: '201': description: A new item. content: application/json: schema: "$ref": "#/components/schemas/Item" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const itemCreate = { code: itemCode, name: "Item Name", description: "Item Description", external_sku: "a35JE-44", accounting_code: "item-code-127", revenue_schedule_type: "at_range_end", custom_fields: [{ name: "custom-field-1", value: "Custom Field 1 value" }] } const item = await client.createItem(itemCreate) console.log('Created Item: ', item.code) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: item_create = { "code": item_code, "name": "Item Name", "description": "Item Description", "external_sku": "a35JE-44", "accounting_code": "item-code-127", "revenue_schedule_type": "at_range_end", "custom_fields": [{ "name": "custom-field-1", "value": "Custom Field 1 value" }] } item = client.create_item(item_create) print("Created Item %s" % item) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var itemReq = new ItemCreate() { Code = itemCode, Name = "Item Name", Description = "Item Description", ExternalSku = "a35JE-44", AccountingCode = "item-code-127", RevenueScheduleType = RevenueScheduleType.AtRangeEnd, CustomFields = new List() { new CustomField() { Name = "custom-field-1", Value = "Custom Field 1 value" } } }; Item item = client.CreateItem(itemReq); Console.WriteLine($"Created item {item.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin item_create = { code: item_code, name: "Item Name", description: "Item Description", external_sku: "a35JE-44", accounting_code: "item-code-127", revenue_schedule_type: "at_range_end", custom_fields: [{ name: "custom-field-1", value: "Custom Field 1 value" }] } item = @client.create_item(body: item_create) puts "Created Item #{item}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { ItemCreate itemReq = new ItemCreate(); itemReq.setCode(itemCode); itemReq.setName("Item Name"); itemReq.setDescription("Item Description"); itemReq.setExternalSku("a35JE-44"); itemReq.setAccountingCode("item-code-127"); itemReq.setRevenueScheduleType(Constants.RevenueScheduleType.AT_RANGE_END); List customFields = new ArrayList<>(); CustomField customField = new CustomField(); customField.setName("custom-field-1"); customField.setValue("Custom Field 1 value"); customFields.add(customField); itemReq.setCustomFields(customFields); Item item = client.createItem(itemReq); System.out.println("Created item " + item.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $item_create = [ "code" => $item_code, "name" => "Coffee Grinder", "description" => "A professional-grade bean grinder." ]; $item = $client->createItem($item_create); echo 'Created Item:' . PHP_EOL; var_dump($item); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "itemReq := &recurly.ItemCreate{\n\tCode: &itemCode,\n\tName: \ recurly.String(\"Item Name\"),\n\tDescription: recurly.String(\"Item Description\"),\n\tExternalSku: recurly.String(\"a35JE-44\"),\n\tAccountingCode: \ recurly.String(\"item-code-127\"),\n\tRevenueScheduleType: recurly.String(\"at_range_end\"),\n}\n\nitem, err := client.CreateItem(itemReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Item: %v\", item.Id)" "/items/{item_id}": get: tags: - item operationId: get_item summary: Fetch an item parameters: - "$ref": "#/components/parameters/item_id" responses: '200': description: An item. content: application/json: schema: "$ref": "#/components/schemas/Item" '404': description: Incorrect site or item ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const item = await client.getItem(itemId) console.log('Fetched item: ', item.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: item = client.get_item(item_id) print("Got Item %s" % item) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Item item = client.GetItem(itemId); Console.WriteLine($"Fetched item {item.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin item = @client.get_item(item_id: item_id) puts "Got Item #{item}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Item item = client.getItem(itemId); System.out.println("Fetched item: " + item.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $item = $client->getItem($item_id); echo 'Got Item:' . PHP_EOL; var_dump($item); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "item, err := client.GetItem(itemID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Item: %v\", item.Id)" put: tags: - item operationId: update_item summary: Update an active item parameters: - "$ref": "#/components/parameters/item_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/ItemUpdate" required: true responses: '200': description: The updated item. content: application/json: schema: "$ref": "#/components/schemas/Item" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or item ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const itemUpdate = { name: 'New Item Name', description: 'New Item Description' } const item = await client.updateItem(itemId, itemUpdate) console.log('Updated item: ', item) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: item_update = { "name": "New Item Name", "description": "New Item Description", } item = client.update_item(item_id, item_update) print("Updated Item %s" % item) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var itemReq = new ItemUpdate() { Name = "New Item Name", Description = "New Item Description", }; Item item = client.UpdateItem(itemId, itemReq); Console.WriteLine(item.Name); Console.WriteLine(item.Description); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin item_update = { name: "New Item Name", description: "New Item Description" } item = @client.update_item( item_id: item_id, body: item_update ) puts "Updated Item #{item}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final ItemUpdate itemUpdate = new ItemUpdate(); itemUpdate.setName("New Item Name"); itemUpdate.setDescription("New Item Description"); final Item item = client.updateItem(itemId, itemUpdate); System.out.println("Updated item: " + item.getCode()); System.out.println(item.getName()); System.out.println(item.getDescription()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $item_update = [ "name" => "Dark Roast Coffee Beans", "description" => "A special dark roast version.", ]; $item = $client->updateItem($item_id, $item_update); echo 'Updated Item:' . PHP_EOL; var_dump($item); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.ItemUpdate{\n\tName: recurly.String(\"Pothos Plant\"),\n\tDescription: recurly.String(\"A sturdy houseplant\"),\n}\nitem, err := client.UpdateItem(itemID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Updated Item: %v\", item.Id)" delete: tags: - item operationId: deactivate_item summary: Deactivate an item parameters: - "$ref": "#/components/parameters/item_id" description: Deactivating an item makes it unavailable for new purchases. It will not affect existing line items. responses: '200': description: An item. content: application/json: schema: "$ref": "#/components/schemas/Item" '422': description: Item may already be inactive. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const item = await client.deactivateItem(itemId) console.log('Deleted item: ', item.code) } catch (err) { if (err && err.type === 'not-found') { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it throw err } - lang: Python source: | try: item = client.deactivate_item(item_id) print("Deactivated Item %s" % item) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Item item = client.DeactivateItem(itemId); Console.WriteLine($"Deactivated item {item.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin item = @client.deactivate_item(item_id: item_id) puts "Deactivated Item #{item}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { Item item = client.deactivateItem(itemId); System.out.println("deactivated item " + item.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $item = $client->deactivateItem($item_id); echo 'Deactivated Item:' . PHP_EOL; var_dump($item); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "deactivatedItem, err := client.DeactivateItem(itemID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Item deactivated: %s\", deactivatedItem.Code)" "/items/{item_id}/reactivate": parameters: - "$ref": "#/components/parameters/item_id" put: tags: - item operationId: reactivate_item summary: Reactivate an inactive item description: Reactivating an item makes it available for new purchases. It will not affect existing line items. responses: '200': description: An item. content: application/json: schema: "$ref": "#/components/schemas/Item" '404': description: Incorrect site or item ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Item is already active. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const item = await client.reactivateItem(itemId) console.log('Reactivated item: ', item.code) } catch (err) { if (err && err.type === 'not_found') { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it throw err } - lang: Python source: | try: item = client.reactivate_item(item_id) print("Reactivated Item %s" % item) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Item item = client.ReactivateItem(itemId); Console.WriteLine($"Reactivated item {item.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin item = @client.reactivate_item(item_id: item_id) puts "Reactivated Item #{item}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Item item = client.reactivateItem(itemId); System.out.println("Reactivated item: " + item.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $item = $client->reactivateItem($item_id); echo 'Reactivate Item:' . PHP_EOL; var_dump($item); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "item, err := client.ReactivateItem(itemID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Reactivated Item: %s\", item.Id)" "/measured_units": get: tags: - measured_unit operationId: list_measured_unit summary: List a site's measured units description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of the site's measured units. content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnitList" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] post: tags: - measured_unit operationId: create_measured_unit summary: Create a new measured unit requestBody: content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnitCreate" required: true responses: '201': description: A new measured unit. content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnit" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/measured_units/{measured_unit_id}": get: tags: - measured_unit operationId: get_measured_unit summary: Fetch a measured unit parameters: - "$ref": "#/components/parameters/measured_unit_id" responses: '200': description: An item. content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnit" '404': description: Incorrect site or measured unit ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] put: tags: - measured_unit operationId: update_measured_unit summary: Update a measured unit parameters: - "$ref": "#/components/parameters/measured_unit_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnitUpdate" required: true responses: '200': description: The updated measured_unit. content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnit" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or measured unit ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] delete: tags: - measured_unit operationId: remove_measured_unit summary: Remove a measured unit description: A mesured unit cannot be deleted if it is used by an active plan. parameters: - "$ref": "#/components/parameters/measured_unit_id" responses: '200': description: A measured unit. content: application/json: schema: "$ref": "#/components/schemas/MeasuredUnit" '422': description: Measured unit may already be inactive. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/invoices": get: tags: - invoice operationId: list_invoices summary: List a site's invoices description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_invoice_type" responses: '200': description: A list of the site's invoices. content: application/json: schema: "$ref": "#/components/schemas/InvoiceList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const invoices = client.listInvoices({ params: { limit: 200 } }) for await (const invoice of invoices.each()) { console.log(invoice.number) } - lang: Python source: | params = {"limit": 200} invoices = client.list_invoices(params=params).items() for invoice in invoices: print(invoice.number) - lang: ".NET" source: | var optionalParams = new ListInvoicesParams() { Limit = 200 }; var invoices = client.ListInvoices(optionalParams); foreach(Invoice invoice in invoices) { Console.WriteLine(invoice.Number); } - lang: Ruby source: | params = { limit: 200 } invoices = @client.list_invoices(params: params) invoices.each do |invoice| puts "Invoice: #{invoice.number}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager invoices = client.listInvoices(params); for (Invoice invoice : invoices) { System.out.println(invoice.getNumber()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $invoices = $client->listInvoices($options); foreach($invoices as $invoice) { echo 'Invoice: ' . $invoice->getNumber() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListInvoicesParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ninvoices, err := client.ListInvoices(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor invoices.HasMore() {\n\terr := invoices.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, invoice := range invoices.Data() {\n\t\tfmt.Printf(\"Invoice %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tinvoice.Id,\n\t\t\tinvoice.Number,\n\t\t)\n\t}\n}" "/invoices/{invoice_id}": get: tags: - invoice operationId: get_invoice summary: Fetch an invoice parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: An invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.getInvoice(invoiceId) console.log('Fetched Invoice: ', invoice.number) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.get_invoice(invoice_id) print("Got Invoice %s" % invoice) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Invoice invoice = client.GetInvoice(invoiceId); Console.WriteLine($"Fetched invoice #{invoice.Number}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.get_invoice(invoice_id: invoice_id) puts "Got invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.getInvoice(invoiceId); System.out.println("Fetched invoice " + invoice.getNumber()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->getInvoice($invoice_id); echo 'Got Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "invoice, err := client.GetInvoice(invoiceID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Invoice: %v\", invoice)" put: tags: - invoice operationId: update_invoice summary: Update an invoice parameters: - "$ref": "#/components/parameters/invoice_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/InvoiceUpdate" required: true responses: '200': description: An invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoiceUpdate = { customerNotes: "New notes", termsAndConditions: "New terms and conditions" } const invoice = await client.updateInvoice(invoiceId, invoiceUpdate) console.log('Edited invoice: ', invoice.number) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice_update = { "customer_notes": "New Notes", "terms_and_conditions": "New Terms and Conditions", } invoice = client.update_invoice(invoice_id, invoice_update) print("Updated Invoice %s" % invoice.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { var invoiceReq = new InvoiceUpdate() { CustomerNotes = "New Notes", TermsAndConditions = "New Terms and Conditions" }; Invoice invoice = client.UpdateInvoice(invoiceId, invoiceReq); Console.WriteLine($"Edited invoice #{invoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice_update = { customer_notes: "New Notes", terms_and_conditions: "New Terms and Conditions" } invoice = @client.update_invoice(invoice_id: invoice_id, body: invoice_update) puts "Updated invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final InvoiceUpdate invoiceUpdate = new InvoiceUpdate(); invoiceUpdate.setCustomerNotes("New notes"); invoiceUpdate.setTermsAndConditions("New terms and conditions"); final Invoice invoice = client.updateInvoice(invoiceId, invoiceUpdate); System.out.println("Edited invoice " + invoice.getNumber()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice_update = [ "customer_notes" => "New Notes", "terms_and_conditions" => "New terms and conditions", ]; $invoice = $client->updateInvoice($invoice_id, $invoice_update); echo 'Updated Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.InvoiceUpdate{\n\tCustomerNotes: recurly.String(\"New Notes\"),\n\tTermsAndConditions: recurly.String(\"New Terms and Conditions\"),\n}\ninvoice, err := client.UpdateInvoice(invoiceID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Invoice: %s\", invoice.Id)" "/invoices/{invoice_id}.pdf": get: tags: - invoice operationId: get_invoice_pdf summary: Fetch an invoice as a PDF parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: An invoice as a PDF. content: application/pdf: schema: "$ref": "#/components/schemas/BinaryFile" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.getInvoicePdf(invoiceId) console.log('Fetched Invoice: ', invoice) const filename = `${downloadDirectory}/nodeinvoice-${invoiceId}.pdf` await fs.writeFile(filename, invoice.data, 'binary', (err) => { // throws an error, you could also catch it here if (err) throw err; // success case, the file was saved console.log('Saved Invoice PDF to', filename) }) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.get_invoice_pdf(invoice_id) print("Got Invoice %s" % invoice) filename = "%s/pythoninvoice-%s.pdf" % (download_directory, invoice_id) with open(filename, 'wb') as file: file.write(invoice.data) print("Saved Invoice PDF to %s" % filename) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { BinaryFile invoice = client.GetInvoicePdf(invoiceId); string filename = $"{downloadDirectory}/dotnetinvoice-{invoiceId}.pdf"; System.IO.File.WriteAllBytes(filename, invoice.Data); Console.WriteLine($"Saved Invoice PDF to {filename}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.get_invoice_pdf(invoice_id: invoice_id) puts "Got invoice #{invoice}" filename = "#{download_directory}/rubyinvoice-#{invoice_id}.pdf" IO.write(filename, invoice.data) puts "Saved Invoice PDF to #{filename}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final BinaryFile invoice = client.getInvoicePdf(invoiceId); //System.out.println("Fetched invoice " + invoice.getData()); String filename = downloadDirectory + "/javainvoice-" + invoiceId + ".pdf"; FileOutputStream fos = new FileOutputStream(filename); fos.write(invoice.getData()); fos.close(); System.out.println("Saved Invoice PDF to " + filename); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } catch (java.io.IOException e) { System.out.println("Unexpected File Writing Error: " + e.toString()); } - lang: PHP source: | try { $invoice = $client->getInvoicePdf($invoice_id); echo 'Got Invoice PDF:' . PHP_EOL; var_dump($invoice); $invoice_fp = fopen("php-invoice-" . $invoice_id . ".pdf", "w"); fwrite($invoice_fp, $invoice->getData()); fclose($invoice_fp); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } "/invoices/{invoice_id}/collect": put: tags: - invoice operationId: collect_invoice summary: Collect a pending or past due, automatic invoice description: Force a collection attempt using the stored billing information. This will trigger a transaction outside of Recurly's normal retry logic. parameters: - "$ref": "#/components/parameters/invoice_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollect" required: false responses: '200': description: The updated invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Tried collecting a manual or closed invoice, or there was an error processing the transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.collectInvoice(invoiceId) console.log('Collected invoice: ', invoice.number) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.collect_invoice(invoice_id) print("Collected Invoice %s" % invoice) except recurly.errors.NotFoundError as e: print("Invoice not found") - lang: ".NET" source: | try { Invoice invoice = client.CollectInvoice(invoiceId); Console.WriteLine($"Collected invoice #{invoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.collect_invoice(invoice_id: invoice_id) puts "Collected invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.collectInvoice(invoiceId); System.out.println("Collected invoice: " + invoice.getNumber()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->collectInvoice($invoice_id); echo 'Collected Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "collectInvoiceParams := &recurly.CollectInvoiceParams{\n\tBody: &recurly.InvoiceCollect{\n\t\tTransactionType: recurly.String(\"moto\"),\n\t},\n}\n\ncollectedInvoice, err := client.CollectInvoice(invoiceID, collectInvoiceParams)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Collected Invoice: %v\", collectedInvoice)" "/invoices/{invoice_id}/mark_failed": put: tags: - invoice operationId: mark_invoice_failed summary: Mark an open invoice as failed description: | Indicates that the invoice was not successfully paid for and that collection attempts should stop. This functionality is mostly used to halt the dunning procedures for an invoice. Only invoices with the `pending`, `processing` or `past_due` states can be marked as failed. parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: The updated invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Tried marking a closed (successful or failed) invoice as failed. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.markInvoiceFailed(invoiceId) console.log('Failed invoice: ', invoice.number) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.mark_invoice_failed(invoice_id) print("Failed Invoice %s" % invoice.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Invoice invoice = client.MarkInvoiceFailed(invoiceId); Console.WriteLine($"Failed invoice #{invoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.mark_invoice_failed(invoice_id: invoice_id) puts "Failed invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.markInvoiceFailed(invoiceId); System.out.println("Failed invoice: " + invoice.getNumber()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->markInvoiceFailed($invoice_id); echo 'Failed Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "invoice, err := client.MarkInvoiceFailed(invoiceID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Invoice failed: %v\", invoice)" "/invoices/{invoice_id}/mark_successful": put: tags: - invoice operationId: mark_invoice_successful summary: Mark an open invoice as successful description: | Indicates that the invoice was successfully paid for and that automated collection attempts should stop - this functionality is typically used to indicate that payment was received via another method and that revenue should be recognized. Only invoices with the `pending`, `processing`, `past_due` or `failed` states can be marked as paid. parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: The updated invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Tried marking a closed (successful or failed) invoice as successful. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.markInvoiceSuccessful(invoiceId) console.log(`Marked invoice #${invoice.number} successful`) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: params = {"limit": 200} invoice = client.mark_invoice_successful(invoice_id, params=params) print("Marked Invoice successful %s" % invoice) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { Invoice invoice = client.MarkInvoiceSuccessful(invoiceId); Console.WriteLine($"Marked invoice #{invoice.Number} successful"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.mark_invoice_successful(invoice_id: invoice_id) puts "Marked invoice sucessful #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.markInvoiceSuccessful(invoiceId); System.out.println("Marked invoice " + invoice.getNumber() + " successful"); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->markInvoiceSuccessful($invoice_id); echo 'Marked Invoice Successful:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "invoice, err := client.MarkInvoiceSuccessful(invoiceID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Marked Invoice Successful: %v\", invoice)" "/invoices/{invoice_id}/reopen": put: tags: - invoice operationId: reopen_invoice summary: Reopen a closed, manual invoice parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: The updated invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Tried reopening an automatic transaction, or an invoice that wasn't closed (`successful` or `failed`). content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.reopenInvoice(invoiceId) console.log('Reopened invoice: ', invoice.number) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.reopen_invoice(invoice_id) print("Reopened Invoice %s" % invoice.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Invoice invoice = client.ReopenInvoice(invoiceId); Console.WriteLine($"Reopened invoice #{invoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice = @client.reopen_invoice(invoice_id: invoice_id) puts "Reopened invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.reopenInvoice(invoiceId); System.out.println("Reopened invoice: " + invoice.getNumber()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->reopenInvoice($invoice_id); echo 'Reopened Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "invoice, err := client.ReopenInvoice(invoiceID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Reopened Invoice: %v\", invoice)" "/invoices/{invoice_id}/void": put: tags: - invoice operationId: void_invoice summary: Void a credit invoice. description: Invoice must be a credit invoice (`type=credit`) and cannot be closed (`state=closed`), processing (`state=processing`), or already voided. parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: The updated invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invoice did not meet the conditions to be voided. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoice = await client.voidInvoice(invoiceId) console.log('Voided invoice: ', invoice) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice = client.void_invoice(invoice_id) print("Voided Invoice %s" % invoice.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: Ruby source: | begin invoice = @client.void_invoice(invoice_id: invoice_id) puts "Voided invoice #{invoice}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Invoice invoice = client.voidInvoice(invoiceId); System.out.println("Voided invoice " + invoice.getId()); } catch (final ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (final ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $invoice = $client->voidInvoice($invoice_id); echo 'Voided Invoice:' . PHP_EOL; var_dump($invoice); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "invoice, err := client.VoidInvoice(invoiceID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Voided Invoice: %v\", invoice)" "/invoices/{invoice_id}/transactions": post: tags: - invoice operationId: record_external_transaction summary: Record an external payment for a manual invoices. description: This endpoint allows you to record an offline payment that was not captured through your gateway. It will throw an error for an auto-collecting invoice. parameters: - "$ref": "#/components/parameters/invoice_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/ExternalTransaction" required: true responses: '200': description: The recorded transaction. content: application/json: schema: "$ref": "#/components/schemas/Transaction" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invoice did not meet the conditions for an offline transaction. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const externalTrx = { description: "A check collected outside of Recurly", amount: 10.0, payment_method: 'check' } const transaction = await client.recordExternalTransaction(invoiceId, externalTrx) console.log('External Transaction: ', transaction) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } "/invoices/{invoice_id}/line_items": get: tags: - line_item operationId: list_invoice_line_items summary: List an invoice's line items description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/invoice_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_line_item_original" - "$ref": "#/components/parameters/filter_line_item_state" - "$ref": "#/components/parameters/filter_line_item_type" responses: '200': description: A list of the invoice's line items. content: application/json: schema: "$ref": "#/components/schemas/LineItemList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const lineItems = client.listInvoiceLineItems(invoiceId, { params: { limit: 200 } }) for await (const lineItem of lineItems.each()) { console.log(lineItem.id) } - lang: Python source: | try: params = {"limit": 200} line_items = client.list_invoice_line_items(invoice_id, params=params).items() for item in line_items: print("Invoice Line Items %s" % item.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | var lineItems = client.ListInvoiceLineItems(invoiceId); foreach(LineItem lineItem in lineItems) { Console.WriteLine(lineItem.Id); } - lang: Ruby source: | params = { limit: 200 } line_items = @client.list_invoice_line_items( invoice_id: invoice_id, params: params ) line_items.each do |line_item| puts "Line Item: #{line_item.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); Pager lineItems = client.listInvoiceLineItems(invoiceId, params); for (LineItem lineItem : lineItems) { System.out.println(lineItem.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $invoice_line_items = $client->listInvoiceLineItems($invoice_id, $options); foreach($invoice_line_items as $line_item) { echo 'Invoice Line Item: ' . $line_item->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListInvoiceLineItemsParams{\n\tSort: recurly.String(\"created_at\"),\n}\nlineItems, err := client.ListInvoiceLineItems(invoiceID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor lineItems.HasMore() {\n\terr := lineItems.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, lineItem := range lineItems.Data() {\n\t\tfmt.Printf(\"Invoice Line Item %3d: %s\\n\",\n\t\t\ti,\n\t\t\tlineItem.Id,\n\t\t)\n\t}\n}" "/invoices/{invoice_id}/coupon_redemptions": get: tags: - coupon_redemption operationId: list_invoice_coupon_redemptions summary: Show the coupon redemptions applied to an invoice description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/invoice_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the the coupon redemptions associated with the invoice. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemptionList" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const redemptions = client.listInvoiceCouponRedemptions(invoiceId, { params: { limit: 200 } }) for await (const redemption of redemptions.each()) { console.log(redemption.id) } - lang: Python source: | params = {"limit": 200} redemptions = client.list_invoice_coupon_redemptions(invoice_id, params=params).items() for redemption in redemptions: print("Invoice Coupon Redemption %s" % redemption) - lang: ".NET" source: | var couponRedemptions = client.ListInvoiceCouponRedemptions(invoiceId); foreach(CouponRedemption redemption in couponRedemptions) { Console.WriteLine(redemption.Id); } - lang: Ruby source: | params = { limit: 200 } coupon_redemptions = @client.list_invoice_coupon_redemptions( invoice_id: invoice_id, params: params ) coupon_redemptions.each do |redemption| puts "CouponRedemption: #{redemption.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager redemptions = client.listInvoiceCouponRedemptions(invoiceId, params); for (CouponRedemption redemption : redemptions) { System.out.println(redemption.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $invoice_coupon_redemptions = $client->listInvoiceCouponRedemptions($invoice_id, $options); foreach($invoice_coupon_redemptions as $redemption) { echo 'Invoice Coupon Redemption: ' . $redemption->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListInvoiceCouponRedemptionsParams{\n\tSort: recurly.String(\"created_at\"),\n}\nredemptions, err := client.ListInvoiceCouponRedemptions(invoiceID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor redemptions.HasMore() {\n\terr := redemptions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, redemption := range redemptions.Data() {\n\t\tfmt.Printf(\"Invoice Coupon Redemption %3d: %s\\n\",\n\t\t\ti,\n\t\t\tredemption.Id,\n\t\t)\n\t}\n}" "/invoices/{invoice_id}/related_invoices": get: tags: - invoice operationId: list_related_invoices summary: List an invoice's related credit or charge invoices description: | Related invoices provide a link between credit invoices and the charge invoices that they are refunding. For a charge invoice the related invoices will be credit invoices. For a credit invoice the related invoices will be charge invoices. See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/invoice_id" responses: '200': description: A list of the credit or charge invoices associated with the invoice. content: application/json: schema: "$ref": "#/components/schemas/InvoiceList" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const invoices = client.listRelatedInvoices(invoiceId, { params: { limit: 200 } }) for await (const invoice of invoices.each()) { console.log(invoice.number) } - lang: Python source: | try: params = {"limit": 200} related_invoices = client.list_related_invoices(invoice_id, params=params).items() for invoice in related_invoices: print("Related invoice %s" % invoice.id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | var invoices = client.ListRelatedInvoices(invoiceId); foreach(Invoice invoice in invoices) { Console.WriteLine(invoice.Number); } - lang: Ruby source: | params = { limit: 200 } invoices = @client.list_related_invoices( invoice_id: invoice_id, params: params ) invoices.each do |invoice| puts "Invoice: #{invoice.number}" end - lang: Java source: | final Pager invoices = client.listRelatedInvoices(invoiceId); for (Invoice invoice : invoices) { System.out.println(invoice.getNumber()); } - lang: PHP source: | $related_invoices = $client->listRelatedInvoices($invoice_id); foreach($related_invoices as $invoice) { echo 'Related Invoice: ' . $invoice->getId() . PHP_EOL; } - lang: Go source: "invoices, err := client.ListRelatedInvoices(invoiceID)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor invoices.HasMore() {\n\terr := invoices.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, invoice := range invoices.Data() {\n\t\tfmt.Printf(\"Related Invoice %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tinvoice.Id,\n\t\t\tinvoice.Number,\n\t\t)\n\t}\n}" "/invoices/{invoice_id}/refund": post: tags: - invoice operationId: refund_invoice summary: Refund an invoice description: | There are two ways to do a refund: * refund a specific amount which is divided across all the line items. * refund quantities of line items. If you want to refund the entire refundable amount on the invoice, the simplest way is to do `type=amount` without specifiying an `amount`. parameters: - "$ref": "#/components/parameters/invoice_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/InvoiceRefund" required: true responses: '201': description: Returns the new credit invoice. content: application/json: schema: "$ref": "#/components/schemas/Invoice" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or invoice ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const invoiceRefund = { creditCustomerNotes: "Notes on credits", type: "amount", // could also be "line_items" amount: 100 } const invoice = await client.refundInvoice(invoiceId, invoiceRefund) console.log('Refunded invoice: ', invoice.number) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: invoice_refund = {"type": "amount", "amount": 100} invoice = client.refund_invoice(invoice_id, invoice_refund) print("Refunded Invoice %s" % invoice) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var refundReq = new InvoiceRefund() { CreditCustomerNotes = "Notes on credits", Type = InvoiceRefundType.Amount, // could also be "line_items" Amount = 100 }; Invoice invoice = client.RefundInvoice(invoiceId, refundReq); Console.WriteLine($"Refunded Invoice #{invoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin invoice_refund = { type: "amount", amount: 100, } invoice = @client.refund_invoice( invoice_id: invoice_id, body: invoice_refund ) puts "Refunded invoice #{invoice}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final InvoiceRefund invoiceRefund = new InvoiceRefund(); invoiceRefund.setCreditCustomerNotes("Notes on credits"); invoiceRefund.setType(Constants.InvoiceRefundType.AMOUNT); // could also be "line_items" invoiceRefund.setAmount(new BigDecimal("100")); final Invoice invoice = client.refundInvoice(invoiceId, invoiceRefund); System.out.println("Refunded invoice " + invoice.getNumber()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $refund = [ "type" => "amount", "amount" => 1 ]; $invoice_collection = $client->refundInvoice($invoice_id, $refund); echo 'Refunded Invoice:' . PHP_EOL; var_dump($invoice_collection); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "refundReq := &recurly.InvoiceRefund{\n\tType: recurly.String(\"amount\"),\n\tAmount: recurly.Float(1),\n\tExternalRefund: &recurly.ExternalRefund{\n\t\tPaymentMethod: recurly.String(\"credit_card\"),\n\t},\n}\ninvoice, err := client.RefundInvoice(invoiceID, refundReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Refunded Invoice: %v\", invoice)" "/line_items": get: tags: - line_item operationId: list_line_items summary: List a site's line items description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_line_item_original" - "$ref": "#/components/parameters/filter_line_item_state" - "$ref": "#/components/parameters/filter_line_item_type" responses: '200': description: A list of the site's line items. content: application/json: schema: "$ref": "#/components/schemas/LineItemList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const lineItems = client.listLineItems({ params: { limit: 200 } }) for await (const item of lineItems.each()) { console.log(`Item ${item.id} for ${item.amount}`) } - lang: Python source: | params = {"limit": 200} line_items = client.list_line_items(params=params).items() for line_item in line_items: print(line_item.id) - lang: ".NET" source: | var optionalParams = new ListLineItemsParams() { Limit = 200 }; var lineItems = client.ListLineItems(optionalParams); foreach(LineItem item in lineItems) { Console.WriteLine($"Item {item.Uuid} for {item.Amount}"); } - lang: Ruby source: | params = { limit: 200 } line_items = @client.list_line_items( params: params ) line_items.each do |line_item| puts "LineItem: #{line_item.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager lineItems = client.listLineItems(params); for (LineItem lineItem : lineItems) { System.out.println("Item " + lineItem.getUuid() + " for " + lineItem.getAmount()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $line_items = $client->listLineItems($options); foreach($line_items as $line_item) { echo 'Line item: ' . $line_item->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListLineItemsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nlineItems, err := client.ListLineItems(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor lineItems.HasMore() {\n\terr := lineItems.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, lineItem := range lineItems.Data() {\n\t\tfmt.Printf(\"Line Item %3d: %s\\n\",\n\t\t\ti,\n\t\t\tlineItem.Id,\n\t\t)\n\t}\n}" "/line_items/{line_item_id}": get: tags: - line_item operationId: get_line_item summary: Fetch a line item parameters: - "$ref": "#/components/parameters/line_item_id" responses: '200': description: A line item. content: application/json: schema: "$ref": "#/components/schemas/LineItem" '404': description: Incorrect site or line item ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const lineItem = await client.getLineItem(lineItemId) console.log('Fetched line item: ', lineItem.uuid) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: line_item = client.get_line_item(line_item_id) print("Got LineItem %s" % line_item) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { LineItem lineItem = client.GetLineItem(lineItemId); Console.WriteLine($"Fetched line item {lineItem.Uuid}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin line_item = @client.get_line_item(line_item_id: line_item_id) puts "Got LineItem #{line_item}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final LineItem lineItem = client.getLineItem(lineItemId); System.out.println("Fetched line item " + lineItem.getUuid()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $line_item = $client->getLineItem($line_item_id); echo 'Got LineItem:' . PHP_EOL; var_dump($line_item); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "lineItem, err := client.GetLineItem(lineItemID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Line Item: %v\", lineItem)" delete: tags: - line_item operationId: remove_line_item summary: Delete an uninvoiced line item parameters: - "$ref": "#/components/parameters/line_item_id" responses: '204': description: Line item deleted. '404': description: Incorrect site or line item ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Only pending line items can be deleted. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { await client.removeLineItem(lineItemId) console.log('Removed line item: ', lineItemId) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_line_item(line_item_id) print("Removed LineItem %s" % line_item_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { client.RemoveLineItem(lineItemId); Console.WriteLine($"Removed line item {lineItemId}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.remove_line_item( line_item_id: line_item_id ) puts "Removed LineItem #{line_item_id}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { client.removeLineItem(lineItemId); System.out.println("Removed line item " + lineItemId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $client->removeLineItem($line_item_id); echo 'Removed LineItem: ' . $line_item_id . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "lineItem, err := client.RemoveLineItem(lineItemID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Removed Line Item: %v\", lineItem)" "/plans": get: tags: - plan operationId: list_plans summary: List a site's plans description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of plans. content: application/json: schema: "$ref": "#/components/schemas/PlanList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const plans = client.listPlans({ params: { limit: 200 } }) for await (const plan of plans.each()) { console.log(plan.code) } - lang: Python source: | params = {"limit": 200} plans = client.list_plans(params=params).items() for plan in plans: print(plan.code) - lang: ".NET" source: | var optionalParams = new ListPlansParams() { Limit = 200 }; var plans = client.ListPlans(optionalParams); foreach(Plan plan in plans) { Console.WriteLine(plan.Code); } - lang: Ruby source: | params = { limit: 200 } plans = @client.list_plans(params: params) plans.each do |plan| puts "Plan: #{plan.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager plans = client.listPlans(params); for (Plan plan : plans) { System.out.println(plan.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $plans = $client->listPlans($options); foreach($plans as $plan) { echo 'Plan: ' . $plan->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListPlansParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nplans, err := client.ListPlans(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor plans.HasMore() {\n\terr := plans.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, plan := range plans.Data() {\n\t\tfmt.Printf(\"Plan %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tplan.Id,\n\t\t\tplan.Code,\n\t\t)\n\t}\n}" post: tags: - plan operationId: create_plan summary: Create a plan requestBody: content: application/json: schema: "$ref": "#/components/schemas/PlanCreate" required: true responses: '201': description: A plan. content: application/json: schema: "$ref": "#/components/schemas/Plan" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as 'Code has already been taken.' content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const planCreate = { name: 'Monthly Coffee Subscription', code: planCode, currencies: [ { currency: 'USD', unitAmount: 10000 } ] } const plan = await client.createPlan(planCreate) console.log('Created Plan: ', plan.code) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: plan_create = { "name": "Monthly Coffee Subscription", "code": plan_code, "currencies": [{"currency": "USD", "unit_amount": 10000}], } plan = client.create_plan(plan_create) print("Created Plan %s" % plan) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var planReq = new PlanCreate() { Name = "Monthly Coffee Subscription", Code = planCode, Currencies = new List() { new PlanPricing() { Currency = "USD", UnitAmount = 10000 } } }; Plan plan = client.CreatePlan(planReq); Console.WriteLine($"Created plan {plan.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin plan_create = { code: plan_code, name: plan_name, currencies: [ currency: "USD", setup_fee: 1_000 ], add_ons: [ { name: 'Extra User', code: 'extra_user', currencies: [ { currency: 'USD', unit_amount: 10_000 } ] } ] } plan = @client.create_plan(body: plan_create) puts "Created Plan #{plan}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { PlanCreate planCreate = new PlanCreate(); planCreate.setName("Monthly Coffee Subscription"); planCreate.setCode(planCode); List currencies = new ArrayList(); PlanPricing planPrice = new PlanPricing(); planPrice.setCurrency("USD"); planPrice.setUnitAmount(new BigDecimal("10000")); currencies.add(planPrice); planCreate.setCurrencies(currencies); Plan plan = client.createPlan(planCreate); System.out.println("Created Plan " + planCode); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $plan_create = [ "name" => "Monthly Coffee Subscription", "code" => $plan_code, "currencies" => [ [ "currency" => "USD", "unit_amount" => 10000 ] ] ]; $plan = $client->createPlan($plan_create); echo 'Created Plan:' . PHP_EOL; var_dump($plan); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "planReq := &recurly.PlanCreate{\n\tCode: &planCode,\n\tName: recurly.String(\"Monthly Coffee Subscription\"),\n\tCurrencies: []recurly.PlanPricingCreate{\n\t\t{\n\t\t\tCurrency: \ recurly.String(\"USD\"),\n\t\t\tUnitAmount: recurly.Float(10000),\n\t\t},\n\t},\n}\n\nplan, err := client.CreatePlan(planReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Plan: %v\", plan.Id)" "/plans/{plan_id}": get: tags: - plan operationId: get_plan summary: Fetch a plan parameters: - "$ref": "#/components/parameters/plan_id" responses: '200': description: A plan. content: application/json: schema: "$ref": "#/components/schemas/Plan" '404': description: Incorrect site or plan ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const plan = await client.getPlan(planId) console.log('Fetched plan: ', plan.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: plan = client.get_plan(plan_id) print("Got Plan %s" % plan) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Plan plan = client.GetPlan(planId); Console.WriteLine($"Fetched plan {plan.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin plan = @client.get_plan(plan_id: plan_id) puts "Got plan #{plan}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Plan plan = client.getPlan(planId); System.out.println("Fetched plan " + plan.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $plan = $client->getPlan($plan_id); echo 'Got Plan:' . PHP_EOL; var_dump($plan); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "plan, err := client.GetPlan(planID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Plan: %s\", plan.Id)" put: tags: - plan operationId: update_plan summary: Update a plan parameters: - "$ref": "#/components/parameters/plan_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/PlanUpdate" required: true responses: '201': description: A plan. content: application/json: schema: "$ref": "#/components/schemas/Plan" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as 'Code has already been taken.' content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const planUpdate = { name: 'New monthly coffee subscription' } const plan = await client.updatePlan(planId, planUpdate) console.log('Updated plan: ', plan.code) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: plan_update = { "name": "Monthly Kombucha Subscription", } plan = client.update_plan(plan_id, plan_update) print("Updated Plan %s" % plan) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { var planReq = new PlanUpdate() { Name = "New Monthly Coffee Subscription" }; Plan plan = client.UpdatePlan(planId, planReq); Console.WriteLine($"Updated plan {plan.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin plan_update = { name: "Monthly Kombucha Subscription" } plan = @client.update_plan(plan_id: plan_id, body: plan_update) puts "Updated plan #{plan}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final PlanUpdate planUpdate = new PlanUpdate(); planUpdate.setName("New Monthly Coffee Subscription"); final Plan plan = client.updatePlan(planId, planUpdate); System.out.println("Updated plan " + plan.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $plan_update = [ "name" => "Monthly Tea Subscription" ]; $plan = $client->updatePlan($plan_id, $plan_update); echo 'Updated Plan:' . PHP_EOL; var_dump($plan); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.PlanUpdate{\n\tName: recurly.String(\"Monthly Houseplant Subscription\"),\n}\nplan, err := client.UpdatePlan(planID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Updated Plan: %s\", plan.Id)" delete: tags: - plan operationId: remove_plan summary: Remove a plan parameters: - "$ref": "#/components/parameters/plan_id" responses: '200': description: Plan deleted content: application/json: schema: "$ref": "#/components/schemas/Plan" '404': description: Incorrect site or plan ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const plan = await client.removePlan(planId) console.log('Removed plan: ', plan.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: plan = client.remove_plan(plan_id) print("Removed Plan %s" % plan) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Plan plan = client.RemovePlan(planId); Console.WriteLine($"Removed plan {plan.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin plan = @client.remove_plan(plan_id: plan_id) puts "Removed plan #{plan}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Plan plan = client.removePlan(planId); System.out.println("Removed plan " + plan.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $plan = $client->removePlan($plan_id); echo 'Removed Plan: ' . $plan_id . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "plan, err := client.RemovePlan(planID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Plan: %s\", plan.Id)" "/plans/{plan_id}/add_ons": get: tags: - add-on operationId: list_plan_add_ons summary: List a plan's add-ons description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/plan_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of add-ons. content: application/json: schema: "$ref": "#/components/schemas/AddOnList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or plan ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const addOns = client.listPlanAddOns(planId, { params: { limit: 200 } }) for await (const addOn of addOns.each()) { console.log(addOn.code) } - lang: Python source: | params = {"limit": 200} add_ons = client.list_plan_add_ons(plan_id, params=params).items() for add_on in add_ons: print(add_on.code) - lang: ".NET" source: | var addOns = client.ListPlanAddOns(planId); foreach(AddOn addOn in addOns) { Console.WriteLine(addOn.Code); } - lang: Ruby source: | params = { limit: 200 } add_ons = @client.list_plan_add_ons( plan_id: plan_id, params: params ) add_ons.each do |add_on| puts "AddOn: #{add_on.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager addOns = client.listPlanAddOns(planId, params); for (AddOn addOn : addOns) { System.out.println(addOn.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $plan_add_ons = $client->listPlanAddOns($plan_id, $options); foreach($plan_add_ons as $add_on) { echo 'Plan add-on: ' . $add_on->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListPlanAddOnsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naddOns, err := client.ListPlanAddOns(planID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor addOns.HasMore() {\n\terr := addOns.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, addOn := range addOns.Data() {\n\t\tfmt.Printf(\"Add-On %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\taddOn.Id,\n\t\t\taddOn.Code,\n\t\t)\n\t}\n}" post: tags: - add-on operationId: create_plan_add_on summary: Create an add-on parameters: - "$ref": "#/components/parameters/plan_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/AddOnCreate" required: true responses: '201': description: An add-on. content: application/json: schema: "$ref": "#/components/schemas/AddOn" '404': description: Incorrect site ID or plan ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as 'Code has already been taken.' content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const addOnCreate = { code: 'coffee_grinder', name: 'A quality grinder for your beans', defaultQuantity: 1, currencies: [ { currency: 'USD', unitAmount: 10000 } ] } const addOn = await client.createPlanAddOn(planId, addOnCreate) console.log('Created add-on: ', addOn.code) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: add_on_create = { "code": "coffee_grinder", "name": "A quality grinder for your beans", "default_quantity": 1, "currencies": [{"currency": "USD", "unit_amount": 10000}], } add_on = client.create_plan_add_on(plan_id, add_on_create) print("Created PlanAddOn %s" % add_on) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var addOnReq = new AddOnCreate() { Code = "coffee_grinder", Name = "A quality grinder for your beans", DefaultQuantity = 1, Currencies = new List() { new AddOnPricing() { Currency = "USD", UnitAmount = 10000 } } }; AddOn addOn = client.CreatePlanAddOn(planId, addOnReq); Console.WriteLine($"Created add-on {addOn.Code}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin new_add_on = { code: 'coffee_grinder', name: 'A quality grinder for your beans', default_quantity: 1, currencies: [ { currency: 'USD', unit_amount: 10_000 } ] } add_on = @client.create_plan_add_on(plan_id: plan_id, body: new_add_on) puts "Created plan add-on #{add_on}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { AddOnCreate addOnCreate = new AddOnCreate(); addOnCreate.setCode("coffee-grinder"); addOnCreate.setName("A quality grinder for your beans"); addOnCreate.setDefaultQuantity(1); List currencies = new ArrayList(); AddOnPricing addOnPrice = new AddOnPricing(); addOnPrice.setCurrency("USD"); addOnPrice.setUnitAmount(new BigDecimal("10000.0")); currencies.add(addOnPrice); addOnCreate.setCurrencies(currencies); AddOn addOn = client.createPlanAddOn(planId, addOnCreate); System.out.println("Created add-on " + addOn.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $add_on_create = [ "code" => $add_on_code, "name" => "Fresh beans shipped monthly", "currencies" => [ [ "currency" => "USD", "unit_amount" => 10 ] ] ]; $add_on = $client->createPlanAddOn($plan_id, $add_on_create); echo 'Created Plan:' . PHP_EOL; var_dump($plan); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "addOnReq := &recurly.AddOnCreate{\n\tCode: &addOnCode,\n\tName: recurly.String(\"Fresh beans shipped monthly\"),\n\tCurrencies: []recurly.AddOnPricingCreate{\n\t\t{\n\t\t\tCurrency: \ recurly.String(\"USD\"),\n\t\t\tUnitAmount: recurly.Float(10),\n\t\t},\n\t},\n}\n\nplanAddOn, err := client.CreatePlanAddOn(planID, addOnReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Plan Add-On: %v\", planAddOn.Id)" "/plans/{plan_id}/add_ons/{add_on_id}": get: tags: - add-on operationId: get_plan_add_on summary: Fetch a plan's add-on parameters: - "$ref": "#/components/parameters/plan_id" - "$ref": "#/components/parameters/add_on_id" responses: '200': description: An add-on. content: application/json: schema: "$ref": "#/components/schemas/AddOn" '404': description: Incorrect site, plan or add-on ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const addOn = await client.getPlanAddOn(planId, addOnId) console.log('Fetched add-on: ', addOn.code) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: add_on = client.get_plan_add_on(plan_id, add_on_id) print("Got Plan Add-On %s" % add_on) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AddOn addOn = client.GetPlanAddOn(planId, addOnId); Console.WriteLine($"Fetched add-on {addOn.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin add_on = @client.get_plan_add_on( plan_id: plan_id, add_on_id: add_on_id ) puts "Got plan add-on #{add_on}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final AddOn addOn = client.getPlanAddOn(planId, addOnId); System.out.println("Fetched add-on " + addOn.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $add_on = $client->getPlanAddOn($plan_id, $add_on_id); echo 'Got Plan Add-On:' . PHP_EOL; var_dump($add_on); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "planAddOn, err := client.GetPlanAddOn(planID, planAddOnID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Plan Add-On: %v\", planAddOn)" put: tags: - add-on operationId: update_plan_add_on summary: Update an add-on parameters: - "$ref": "#/components/parameters/plan_id" - "$ref": "#/components/parameters/add_on_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/AddOnUpdate" required: true responses: '201': description: An add-on. content: application/json: schema: "$ref": "#/components/schemas/AddOn" '404': description: Incorrect site, plan, or add-on ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as 'Code has already been taken.' content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const addOnUpdate = { name: 'New AddOn Name', } const addOn = await client.updatePlanAddOn(planId, addOnId, addOnUpdate) console.log('Updated add-on: ', addOn) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: add_on_update = { "name": "New Add-On Name", } add_on = client.update_plan_add_on(plan_id, add_on_id, add_on_update) print("Updated Plan Add-On %s" % add_on) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { var addOnReq = new AddOnUpdate { Name = "New Add-On Name" }; AddOn addOn = client.UpdatePlanAddOn(planId, planAddOnId, addOnReq); Console.WriteLine($"Updated add-on: {addOn.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: "begin\n add_on_update = {\n name: \"A quality grinder for your finest beans\"\n }\n add_on = @client.update_plan_add_on(\n plan_id: plan_id, \n add_on_id: add_on_id, \n body: add_on_update\n )\n puts \"Updated add-on #{add_on}\"\nrescue Recurly::Errors::NotFoundError\n # If the resource was not found, you may want to alert the user or\n # just return nil\n puts \"Resource Not Found\"\nend\n" - lang: Java source: | try { final AddOnUpdate addOnUpdate = new AddOnUpdate(); addOnUpdate.setName("New Add-On Name"); final AddOn addOn = client.updatePlanAddOn(planId, addOnId, addOnUpdate); System.out.println("Updated add-on " + addOn.getCode()); System.out.println(addOn.getName()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $add_on_update = [ "name" => "New AddOn Name", ]; $add_on = $client->updatePlanAddOn($plan_id, $add_on_id, $add_on_update); echo ' Updated Plan AddOn:' . PHP_EOL; var_dump($add_on); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.AddOnUpdate{\n\tName: recurly.String(\"New Add-On Name\"),\n}\nplanAddOn, err := client.UpdatePlanAddOn(planID, planAddOnID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Updated Plan Add-On: %v\", planAddOn)" delete: tags: - add-on operationId: remove_plan_add_on summary: Remove an add-on parameters: - "$ref": "#/components/parameters/plan_id" - "$ref": "#/components/parameters/add_on_id" responses: '200': description: Add-on deleted content: application/json: schema: "$ref": "#/components/schemas/AddOn" '404': description: Incorrect site, plan, or add-on ID. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const addOn = await client.removePlanAddOn(planId, addOnId) console.log('Removed plan add-on: ', addOn) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: add_on = client.remove_plan_add_on(plan_id, add_on_id) print("Removed Plan Add-On %s" % add_on_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AddOn addOn = client.RemovePlanAddOn(planId, planAddOnId); Console.WriteLine($"Removed Plan Add-On: {addOn.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: "begin\n add_on = @client.remove_plan_add_on(\n plan_id: plan_id, \n add_on_id: add_on_id\n )\n puts \"Removed add-on #{add_on}\"\nrescue Recurly::Errors::NotFoundError\n # If the resource was not found, you may want to alert the user or\n # just return nil\n puts \"Resource Not Found\"\nend\n" - lang: Java source: |- try { final AddOn addOn = client.removePlanAddOn(planId, addOnId); System.out.println("Removed add-on " + addOn.getCode()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $add_on = $client->removePlanAddOn($plan_id, $add_on_id); echo 'Removed Plan AddOn:' . PHP_EOL; var_dump($add_on); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "planAddOn, err := client.RemovePlanAddOn(planID, planAddOnID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Removed Plan Add-On: %v\", planAddOn)" "/add_ons": get: tags: - add-on operationId: list_add_ons summary: List a site's add-ons description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_state" responses: '200': description: A list of add-ons. content: application/json: schema: "$ref": "#/components/schemas/AddOnList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or add-on ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const addOns = client.listAddOns({ params: { limit: 200 } }) for await (const addOn of addOns.each()) { console.log(addOn.code) } - lang: Python source: | params = {"limit": 200} add_ons = client.list_add_ons(params=params).items() for add_on in add_ons: print("Add-On %s" % add_on.code) - lang: ".NET" source: | var addOns = client.ListAddOns(); foreach(AddOn addOn in addOns) { Console.WriteLine(addOn.Code); } - lang: Ruby source: | params = { limit: 200 } add_ons = @client.list_add_ons( params: params ) add_ons.each do |add_on| puts "AddOn: #{add_on.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager addOns = client.listAddOns(params); for (AddOn addOn : addOns) { System.out.println(addOn.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $add_ons = $client->listAddOns($options); foreach($add_ons as $addon) { echo 'Add-on: ' . $addon->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListAddOnsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\naddOns, err := client.ListAddOns(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor addOns.HasMore() {\n\terr := addOns.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, addOn := range addOns.Data() {\n\t\tfmt.Printf(\"Add On %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\taddOn.Id,\n\t\t\taddOn.Code,\n\t\t)\n\t}\n}" "/add_ons/{add_on_id}": get: tags: - add-on operationId: get_add_on summary: Fetch an add-on parameters: - "$ref": "#/components/parameters/add_on_id" responses: '200': description: An add-on. content: application/json: schema: "$ref": "#/components/schemas/AddOn" '404': description: Incorrect site or add-on ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const addOn = await client.getAddOn(addOnId) console.log('Fetched add-on: ', addOn) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: add_on = client.get_add_on(add_on_id) print("Got Add-On %s" % add_on) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { AddOn addOn = client.GetAddOn(addOnId); Console.WriteLine($"Fetched add-on: {addOn.Code}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin add_on = @client.get_add_on(add_on_id: add_on_id) puts "Got add-on #{add_on}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final AddOn addOn = client.getAddOn(addOnId); System.out.println("Fetched add-on " + addOn.getCode()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $add_on = $client->getAddOn($add_on_id); echo 'Got Plan Add-On:' . PHP_EOL; var_dump($add_on); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "addOn, err := client.GetAddOn(planAddOnID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Fetched Add-On: %s\", addOn.Id)" "/shipping_methods": get: tags: - shipping_method operationId: list_shipping_methods summary: List a site's shipping methods description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the site's shipping methods. content: application/json: schema: "$ref": "#/components/schemas/ShippingMethodList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const methods = client.listShippingMethods({ params: { limit: 200 } }) for await (const method of methods.each()) { console.log(method.code) } - lang: Python source: | params = {"limit": 200} shipping_methods = client.list_shipping_methods(params=params).items() for shipping_method in shipping_methods: print("Shipping Method %s" % shipping_method.code) - lang: ".NET" source: | var shippingMethods = client.ListShippingMethods(); foreach(ShippingMethod shippingMethod in shippingMethods) { Console.WriteLine(shippingMethod.Code); } - lang: Ruby source: | params = { limit: 200 } shipping_methods = @client.list_shipping_methods( params: params ) shipping_methods.each do |shipping_method| puts "Shipping Method: #{shipping_method.code}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager shippingMethods = client.listShippingMethods(params); for (ShippingMethod shippingMethod : shippingMethods) { System.out.println(shippingMethod.getCode()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $shipping_methods = $client->listShippingMethods($options); foreach($shipping_methods as $shipping_method) { echo 'Shipping Method: ' . $shipping_method->getCode() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListShippingMethodsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nshippingMethods, err := client.ListShippingMethods(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor shippingMethods.HasMore() {\n\terr := shippingMethods.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, method := range shippingMethods.Data() {\n\t\tfmt.Printf(\"Shipping Method %3d: %s, %s\\n\",\n\t\t\ti,\n\t\t\tmethod.Id,\n\t\t\tmethod.Code,\n\t\t)\n\t}\n}" post: tags: - shipping_method operationId: create_shipping_method summary: Create a new shipping method requestBody: content: application/json: schema: "$ref": "#/components/schemas/ShippingMethodCreate" required: true responses: '201': description: A new shipping method. content: application/json: schema: "$ref": "#/components/schemas/ShippingMethod" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/shipping_methods/{shipping_method_id}": get: tags: - shipping_method operationId: get_shipping_method summary: Fetch a shipping method parameters: - "$ref": "#/components/parameters/shipping_method_id" responses: '200': description: A shipping method. content: application/json: schema: "$ref": "#/components/schemas/ShippingMethod" '404': description: Incorrect site or shipping method ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] put: tags: - shipping_method operationId: update_shipping_method summary: Update an active Shipping Method parameters: - "$ref": "#/components/parameters/shipping_method_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/ShippingMethodUpdate" required: true responses: '200': description: The updated shipping method. content: application/json: schema: "$ref": "#/components/schemas/ShippingMethod" '400': description: Bad request, perhaps invalid JSON? content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or shipping method ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] delete: tags: - shipping_method operationId: deactivate_shipping_method summary: Deactivate a shipping method parameters: - "$ref": "#/components/parameters/shipping_method_id" description: Deactivating a shipping method makes it unavailable for new subscriptions or purchases. It will not affect existing subscriptions. responses: '200': description: A shipping method. content: application/json: schema: "$ref": "#/components/schemas/ShippingMethod" '422': description: Shipping method may already be inactive. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/subscriptions": get: tags: - subscription operationId: list_subscriptions summary: List a site's subscriptions description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_subscription_state" responses: '200': description: A list of the site's subscriptions. content: application/json: schema: "$ref": "#/components/schemas/SubscriptionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const subscriptions = client.listSubscriptions({ params: { limit: 200 } }) for await (const subscription of subscriptions.each()) { console.log(subscription.uuid) } - lang: Python source: | params = {"limit": 200} subscriptions = client.list_subscriptions(params=params).items() for subscription in subscriptions: print(subscription.uuid) - lang: ".NET" source: | var optionalParams = new ListSubscriptionsParams() { Limit = 200 }; var subscriptions = client.ListSubscriptions(optionalParams); foreach(Subscription subscription in subscriptions) { Console.WriteLine(subscription.Uuid); } - lang: Ruby source: | params = { limit: 200 } subscriptions = @client.list_subscriptions(params: params) subscriptions.each do |subscription| puts "Subscription: #{subscription.uuid}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager subscriptions = client.listSubscriptions(params); for (Subscription subscription : subscriptions) { System.out.println(subscription.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $subscriptions = $client->listSubscriptions($options); foreach($subscriptions as $sub) { echo 'Subscription: ' . $sub->getUuid() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListSubscriptionsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nsubscriptions, err := client.ListSubscriptions(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor subscriptions.HasMore() {\n\terr := subscriptions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, subscription := range subscriptions.Data() {\n\t\tfmt.Printf(\"Subscription %3d: %s\\n\",\n\t\t\ti,\n\t\t\tsubscription.Id,\n\t\t)\n\t}\n}" post: tags: - subscription operationId: create_subscription summary: Create a new subscription requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionCreate" required: true responses: '201': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as 'You already have a subscription to this plan.' error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let subscriptionReq = { planCode: planCode, currency: `USD`, account: { code: accountCode } } let sub = await client.createSubscription(subscriptionReq) console.log('Created subscription: ', sub.uuid) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: sub_create = { "plan_code": plan_code, "currency": "USD", "account": {"code": account_code}, } sub = client.create_subscription(sub_create) print("Created Subscription %s" % sub) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var subReq = new SubscriptionCreate() { Currency = "USD", Account = new AccountCreate() { Code = accountCode }, PlanCode = planCode, }; Subscription subscription = client.CreateSubscription(subReq); Console.WriteLine($"Created Subscription with Id: {subscription.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription_create = { plan_code: plan_code, currency: "USD", # This can be an existing account or a new account account: { code: account_code, } } subscription = @client.create_subscription( body: subscription_create ) puts "Created Subscription #{subscription}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { SubscriptionCreate subscriptionCreate = new SubscriptionCreate(); AccountCreate accountCreate = new AccountCreate(); accountCreate.setCode(accountCode); subscriptionCreate.setCurrency("USD"); subscriptionCreate.setAccount(accountCreate); subscriptionCreate.setPlanCode(planCode); Subscription subscription = client.createSubscription(subscriptionCreate); System.out.println("Created Subscription with Id: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $sub_create = [ "plan_code" => $plan_code, "currency" => "USD", "account" => [ "code" => $account_code ], ]; $subscription = $client->createSubscription($sub_create); echo 'Created Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "subReq := &recurly.SubscriptionCreate{\n\tPlanCode: recurly.String(planCode),\n\tAccount: &recurly.AccountCreate{\n\t\tCode: recurly.String(accountCode),\n\t},\n\tCurrency: recurly.String(\"USD\"),\n}\n\nsubscription, err := client.CreateSubscription(subReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Subscription: %s\", subscription.Id)" "/subscriptions/{subscription_id}": get: tags: - subscription operationId: get_subscription summary: Fetch a subscription parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const subscription = await client.getSubscription(subscriptionId) console.log('Fetched subscription: ', subscription.uuid) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: subscription = client.get_subscription(subscription_id) print("Got Subscription %s" % subscription) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Subscription subscription = client.GetSubscription(sub.Id); Console.WriteLine($"Fetched Subscription {subscription.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription = @client.get_subscription( subscription_id: subscription_id ) puts "Got Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Subscription subscription = client.getSubscription(subscriptionId); System.out.println("Fetched Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $subscription = $client->getSubscription($subscription_id); echo 'Got Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "sub, err := client.GetSubscription(subID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Subscription: %s\", sub.Id)" put: tags: - subscription operationId: update_subscription summary: Update a subscription description: This only lets you change the subscription settings that have no impact on the billed amount. Use the [Create Subscription Change](#operation/create_subscription_change) endpoint to make those changes. parameters: - "$ref": "#/components/parameters/subscription_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionUpdate" required: true responses: '200': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const update = { termsAndConditions: "Some new terms and conditions", customerNotes: "Some new customer notes" } const subscription = await client.updateSubscription(subscriptionId, update) console.log('Modified subscription: ', subscription.uuid) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: sub_update = {"customer_notes": "New Notes", "terms_and_conditions": "New TaC"} subscription = client.update_subscription(subscription_id, sub_update) print("Modified Subscription %s" % subscription) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var updateReq = new SubscriptionUpdate() { TermsAndConditions = "Some New Terms and Conditions", CustomerNotes = "Some New Customer Notes" }; Subscription subscription = client.UpdateSubscription(subscriptionId, updateReq); Console.WriteLine($"Modified Subscription {subscription.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription_update = { customer_notes: "New Notes", terms_and_conditions: "New ToC" } subscription = @client.update_subscription( subscription_id: subscription_id, body: subscription_update ) puts "Modified Subscription #{subscription}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { final SubscriptionUpdate subUpdate = new SubscriptionUpdate(); subUpdate.setTermsAndConditions("Some new terms and conditions"); subUpdate.setCustomerNotes("Some new customer notes"); final Subscription subscription = client.updateSubscription(subscriptionId, subUpdate); System.out.println("Modified Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $changes = [ "terms_and_conditions" => "Some new terms and conditions", "customer_notes" => "Some new customer notes" ]; $subscription = $client->updateSubscription($subscription_id, $changes); echo 'Modified Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "updateReq := &recurly.SubscriptionUpdate{\n\tTermsAndConditions: recurly.String(\"Some new terms and conditions\"),\n\tCustomerNotes: recurly.String(\"Some new customer notes\"),\n}\nsub, err := client.UpdateSubscription(subID, updateReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Modified Subscription: %s\", sub.Id)" delete: tags: - subscription operationId: terminate_subscription summary: Terminate a subscription description: | Immediately expires the subscription. If the subscription has a paid invoice you may choose to refund all, part or none of last invoice's amount. parameters: - "$ref": "#/components/parameters/subscription_id" - name: refund in: query description: | The type of refund to perform: * `full` - Performs a full refund of the last invoice for the current subscription term. * `partial` - Prorates a refund based on the amount of time remaining in the current bill cycle. * `none` - Terminates the subscription without a refund. In the event that the most recent invoice is a $0 invoice paid entirely by credit, Recurly will apply the credit back to the customer’s account. You may also terminate a subscription with no refund and then manually refund specific invoices. schema: default: none "$ref": "#/components/schemas/RefundTypeEnum" - name: charge in: query description: Applicable only if the subscription has usage based add-ons and unbilled usage logged for the current billing cycle. 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. schema: default: true type: boolean responses: '200': description: An expired subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site ID or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: 'A validation error such as "Cannot expire an inactive subscription." or "Please provide valid values for these parameters: refund."' content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const subscription = await client.terminateSubscription(subscriptionId) console.log('Terminated subscription: ', subscription.uuid) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: subscription = client.terminate_subscription(subscription_id) print("Terminated Subscription %s" % subscription) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { var optionalParams = new TerminateSubscriptionParams() { Refund = RefundType.None }; Subscription subscription = client.TerminateSubscription(subscriptionId, optionalParams); Console.WriteLine($"Terminated Subscription {subscription.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription = @client.terminate_subscription( subscription_id: subscription_id, ) puts "Terminated Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { QueryParams queryParams = new QueryParams(); queryParams.setRefund(Constants.RefundType.NONE); // "full" for a full refund, "partial" for prorated refund client.terminateSubscription(subscriptionId, queryParams); System.out.println("Terminated Subscription: " + subscriptionId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $subscription = $client->terminateSubscription($subscription_id); echo 'Terminated Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "terminateParams := &recurly.TerminateSubscriptionParams{}\nsubscription, err := client.TerminateSubscription(subID, terminateParams)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Terminated Subscription: %v\", subscription)" "/subscriptions/{subscription_id}/cancel": put: tags: - subscription operationId: cancel_subscription summary: Cancel a subscription description: A canceled subscription will continue through its current billing cycle. At the end of the current billing cycle the subscription will expire and the customer will no longer be billed. Canceled subscriptions can be reactivated until the end of the billing cycle. When a future subscription (`state=future`) is canceled it becomes failed `state=failed` and cannot be reactivated. parameters: - "$ref": "#/components/parameters/subscription_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionCancel" required: false responses: '200': description: A canceled or failed subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Only active and future subscriptions can be canceled". content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let expiredSub = await client.cancelSubscription(subscriptionId) console.log('Canceled Subscription: ', expiredSub.uuid) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: subscription = client.cancel_subscription(subscription_id) print("Canceled Subscription %s" % subscription) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Subscription subscription = client.CancelSubscription(subscriptionId); Console.WriteLine($"Canceled Subscription {subscription.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription = @client.cancel_subscription( subscription_id: subscription_id ) puts "Canceled Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Subscription subscription = client.cancelSubscription(subscriptionId); System.out.println("Canceled Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $subscription = $client->cancelSubscription($subscription_id); echo 'Canceled Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "cancelParams := &recurly.CancelSubscriptionParams{\n\tBody: &recurly.SubscriptionCancel{\n\t\tTimeframe: recurly.String(\"bill_date\"),\n\t},\n}\n\nsubscription, err := client.CancelSubscription(subID, cancelParams)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Canceled Subscription: %s\", subscription.Id)" "/subscriptions/{subscription_id}/reactivate": put: tags: - subscription operationId: reactivate_subscription summary: Reactivate a canceled subscription description: | This will bring the subscription back to an active, renewing state on the customer's original billing cycle. Expired or failed subscriptions cannot be reactivated; instead a new subscription plan will need to be applied to the account. parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: An active subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Only canceled subscriptions can be reactivated". content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const subscription = await client.reactivateSubscription(subscriptionId) console.log('Reactivated subscription: ', subscription.uuid) } catch(err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: subscription = client.reactivate_subscription(subscription_id) print("Reactivated Subscription %s" % subscription) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Subscription subscription = client.ReactivateSubscription(subscriptionId); Console.WriteLine($"Reactivated Subscription {subscription.Uuid}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription = @client.reactivate_subscription( subscription_id: subscription_id ) puts "Reactivated Canceled Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Subscription subscription = client.reactivateSubscription(subscriptionId); System.out.println("Reactivated Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $subscription = $client->reactivateSubscription($subscription_id); echo 'Reactivated Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "sub, err := client.ReactivateSubscription(subID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Reactivated Subscription: %s\", sub.Id)" "/subscriptions/{subscription_id}/pause": put: tags: - subscription operationId: pause_subscription summary: Pause subscription description: | This will put a subscription into the pause state at the next renewal. The body of the request must contain the `remaining_pause_cycles` parameter. If the subscription is currently paused and `remaining_pause_cycles` is 0, the subscription will be resumed. Expired, cancelled, or failed subscriptions cannot be paused. parameters: - "$ref": "#/components/parameters/subscription_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionPause" required: true responses: '200': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "remaining_pause_cycles is required". content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let pauseReq = { remaining_pause_cycles: 2, } const subscription = await client.pauseSubscription(subscriptionId, pauseReq) console.log('Paused subscription: ', subscription.id) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: sub_pause = {"remaining_pause_cycles": 10} subscription = client.pause_subscription(subscription_id, sub_pause) print("Paused Subscription %s" % subscription) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var pauseReq = new SubscriptionPause() { RemainingPauseCycles = 2 }; Subscription subscription = client.PauseSubscription(subscriptionId, pauseReq); Console.WriteLine($"Paused Subscription {subscription.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription_pause = { remaining_pause_cycles: 10 } subscription = @client.pause_subscription( subscription_id: subscription_id, body: subscription_pause ) puts "Paused Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final SubscriptionPause subPause = new SubscriptionPause(); subPause.setRemainingPauseCycles(10); final Subscription subscription = client.pauseSubscription(subscriptionId, subPause); System.out.println("Paused Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $sub_pause = [ "remaining_pause_cycles" => 10 ]; $subscription = $client->pauseSubscription($subscription_id, $sub_pause); echo 'Paused Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "pauseReq := &recurly.SubscriptionPause{\n\tRemainingPauseCycles: recurly.Int(1),\n}\nsub, err := client.PauseSubscription(subID, pauseReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Paused Subscription: %s\", sub.Id)" "/subscriptions/{subscription_id}/resume": put: tags: - subscription operationId: resume_subscription summary: Resume subscription description: | This will immediately resume a paused subscription and move it into the active state. The subscription must be in the paused state. Active, expired, cancelled, or failed subscriptions cannot be resumed. parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Unable to resume active subscription". content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const subscription = await client.resumeSubscription(subscriptionId) console.log('Resumed subscription: ', subscription.id) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: subscription = client.resume_subscription(subscription_id) print("Resumed Subscription %s" % subscription) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { Subscription subscription = client.ResumeSubscription(subscriptionId); Console.WriteLine($"Resumed Subscription {subscription.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin subscription = @client.resume_subscription( subscription_id: subscription_id ) puts "Resumed Subscription #{subscription}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final Subscription subscription = client.resumeSubscription(subscriptionId); System.out.println("Resumed Subscription: " + subscription.getUuid()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $subscription = $client->resumeSubscription($subscription_id); echo 'Resumed Subscription:' . PHP_EOL; var_dump($subscription); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "sub, err := client.ResumeSubscription(subID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Resumed Subscription: %s\", sub.Id)" "/subscriptions/{subscription_id}/convert_trial": put: tags: - subscription operationId: convert_trial summary: Convert trial subscription description: This will immediately convert a trial subscription to a fully active paid subscription, creating and collecting an invoice for auto-collecting subsriptions. If the invoice cannot be collected, the subscription will remain in trial. The subscription must be in a trial. Active, paused, expired, cancelled, or failed subscriptions cannot be converted. parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: A subscription. content: application/json: schema: "$ref": "#/components/schemas/Subscription" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Unable to convert active subscription", or a transaction error if the invoice could not be collected. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/subscriptions/{subscription_id}/preview_renewal": get: tags: - subscription operationId: get_preview_renewal summary: Fetch a preview of a subscription's renewal invoice(s) description: The subscriptions's renewal invoice(s) will be returned if they exist; if they don't (for example, if the subscription is not set to renew), it will return an result with no invoices. parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: A preview of the subscription's renewal invoice(s). content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollection" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/subscriptions/{subscription_id}/change": get: tags: - subscription_change operationId: get_subscription_change summary: Fetch a subscription's pending change parameters: - "$ref": "#/components/parameters/subscription_id" responses: '200': description: A subscription's pending change. content: application/json: schema: "$ref": "#/components/schemas/SubscriptionChange" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID or subscription ID or the subscription has no pending change. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Expired subscriptions cannot be changed. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const change = await client.getSubscriptionChange(subscriptionId) console.log('Fetched subscription change: ', change.id) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: change = client.get_subscription_change(subscription_id) print("Got SubscriptionChange %s" % change) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { SubscriptionChange change = client.GetSubscriptionChange(subscriptionId); Console.WriteLine($"Fetched subscription change {change.Id}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin change = @client.get_subscription_change( subscription_id: subscription_id ) puts "Got SubscriptionChange #{change}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { final SubscriptionChange change = client.getSubscriptionChange(subscriptionId); System.out.println("Fetched Subscription change " + change.getId()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $change = $client->getSubscriptionChange($subscription_id); echo 'Got Pending Subscription Change:' . PHP_EOL; var_dump($change); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "subscriptionChange, err := client.GetSubscriptionChange(subID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched subscription change: %s\", subscriptionChange.Id)" post: tags: - subscription_change operationId: create_subscription_change summary: Create a new subscription change description: | Calling this will overwrite an existing, pending subscription change. If a subscription has a pending change, and a change is submitted which matches the subscription as it currently exists, the pending change will be deleted, and you will receive a 204 No Content response. If a subscription has no pending change, and a change is submitted which matches the subscription as it currently exists, a 422 Unprocessable Entity validation error will be returned. parameters: - "$ref": "#/components/parameters/subscription_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionChangeCreate" required: true responses: '201': description: A subscription change. content: application/json: schema: "$ref": "#/components/schemas/SubscriptionChange" '204': description: The previous pending change was reverted. '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Subscription hasn't been changed" or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const subscriptionChangeCreate = { planCode: newPlanCode, timeframe: 'now' } const change = await client.createSubscriptionChange(subscriptionId, subscriptionChangeCreate) console.log('Created subscription change: ', change.id) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: sub_change_create = {"plan_code": new_plan_code, "timeframe": "now"} change = client.create_subscription_change(subscription_id, sub_change_create) print("Created SubscriptionChange %s" % change) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var changeReq = new SubscriptionChangeCreate() { PlanCode = newPlanCode, Timeframe = ChangeTimeframe.Now // choose "now" or "renewal" }; SubscriptionChange change = client.CreateSubscriptionChange(subscriptionId, changeReq); Console.WriteLine($"Created subscription change {change.Id}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin change_create = { timeframe: "now", plan_code: new_plan_code } change = @client.create_subscription_change( subscription_id: subscription_id, body: change_create ) puts "Created SubscriptionChange #{change}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { SubscriptionChangeCreate changeCreate = new SubscriptionChangeCreate(); changeCreate.setPlanCode(newPlanCode); changeCreate.setTimeframe(Constants.ChangeTimeframe.NOW); // choose "now" or "renewal" SubscriptionChange change = client.createSubscriptionChange(subscriptionId, changeCreate); System.out.println("Created subscription " + change.getId()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $change_create = [ "plan_code" => $new_plan_code, "timeframe" => "now" ]; $change = $client->createSubscriptionChange($subscription_id, $change_create); echo 'Created Subscription Change:' . PHP_EOL; var_dump($change); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "changeReq := &recurly.SubscriptionChangeCreate{\n\tPlanCode: recurly.String(newPlanCode),\n\tTimeframe: recurly.String(\"now\"),\n}\nsubscriptionChange, err := client.CreateSubscriptionChange(subID, changeReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Subscription changed: %s\", subscriptionChange.Id)" delete: tags: - subscription_change operationId: remove_subscription_change summary: Delete the pending subscription change parameters: - "$ref": "#/components/parameters/subscription_id" description: Deleting the pending subscription change will cause the current subscription settings to be used on the next renewal. responses: '204': description: Subscription change was deleted. '422': description: Activated subscription changes cannot be deleted. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { await client.removeSubscriptionChange(subscriptionId) console.log('Removed subscription change: ', subscriptionId) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: client.remove_subscription_change(subscription_id) print("Removed SubscriptionChange from Subscription id=%s" % subscription_id) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { client.RemoveSubscriptionChange(subscriptionId); Console.WriteLine($"Removed subscription change from {subscriptionId}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin @client.remove_subscription_change( subscription_id: subscription_id ) puts "Removed SubscriptionChange #{subscription_id}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { client.removeSubscriptionChange(subscriptionId); System.out.println("Removed Subscription change from " + subscriptionId); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $client->removeSubscriptionChange($subscription_id); echo 'Removed Subscription Change: ' . $subscription_id . PHP_EOL; } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "subscriptionChange, err := client.RemoveSubscriptionChange(subID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfmt.Printf(\"Removed Subscription Change: %v\", subscriptionChange)" "/subscriptions/{subscription_id}/change/preview": post: tags: - subscription_change operationId: preview_subscription_change summary: Preview a new subscription change description: Calling this will not save the subscription change or overwrite an existing change. parameters: - "$ref": "#/components/parameters/subscription_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/SubscriptionChangeCreate" required: true responses: '200': description: A subscription change. content: application/json: schema: "$ref": "#/components/schemas/SubscriptionChange" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error such as "Subscription hasn't been changed" or error running the verification transaction. content: application/json: schema: "$ref": "#/components/schemas/ErrorMayHaveTransaction" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/subscriptions/{subscription_id}/invoices": get: tags: - invoice operationId: list_subscription_invoices summary: List a subscription's invoices description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/subscription_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_invoice_type" responses: '200': description: A list of the subscription's invoices. content: application/json: schema: "$ref": "#/components/schemas/InvoiceList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const invoices = client.listSubscriptionInvoices(subscriptionId, { params: { limit: 200 } }) for await (const invoice of invoices.each()) { console.log(invoice.number) } - lang: Python source: | params = {"limit": 200} invoices = client.list_subscription_invoices(subscription_id, params=params).items() for invoice in invoices: print(invoice.number) - lang: ".NET" source: | var subscriptionInvoices = client.ListSubscriptionInvoices(subscriptionId); foreach(Invoice invoice in subscriptionInvoices) { Console.WriteLine(invoice.Number); } - lang: Ruby source: | params = { limit: 200 } invoices = @client.list_subscription_invoices( subscription_id: subscription_id, params: params ) invoices.each do |invoice| puts "Invoice: #{invoice.number}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager invoices = client.listSubscriptionInvoices(subscriptionId, params); for (Invoice invoice : invoices) { System.out.println(invoice.getNumber()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $subscription_invoices = $client->listSubscriptionInvoices($subscription_id, $options); foreach($subscription_invoices as $sub_invoice) { echo 'Subscription Invoice: ' . $sub_invoice->getNumber() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListSubscriptionInvoicesParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nsubInvoices, err := client.ListSubscriptionInvoices(subID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor subInvoices.HasMore() {\n\terr := subInvoices.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, invoice := range subInvoices.Data() {\n\t\tfmt.Printf(\"Subscription Invoice %3d: %s\\n\",\n\t\t\ti,\n\t\t\tinvoice.Id,\n\t\t)\n\t}\n}" "/subscriptions/{subscription_id}/line_items": get: tags: - line_item operationId: list_subscription_line_items summary: List a subscription's line items description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/subscription_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_line_item_original" - "$ref": "#/components/parameters/filter_line_item_state" - "$ref": "#/components/parameters/filter_line_item_type" responses: '200': description: A list of the subscription's line items. content: application/json: schema: "$ref": "#/components/schemas/LineItemList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const lineItems = client.listSubscriptionLineItems(subscriptionId, { params: { limit: 200 } }) for await (const lineItem of lineItems.each()) { console.log(lineItem.id) } - lang: Python source: | params = {"limit": 200} line_items = client.list_subscription_line_items(subscription_id, params=params).items() for line_item in line_items: print(line_item.id) - lang: ".NET" source: | var subscriptionLineItems = client.ListSubscriptionLineItems(subscriptionId); foreach(LineItem lineItem in subscriptionLineItems) { Console.WriteLine(lineItem.Id); } - lang: Ruby source: | params = { limit: 200 } line_items = @client.list_subscription_line_items( subscription_id: subscription_id, params: params ) line_items.each do |line_item| puts "LineItem: #{line_item.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager lineItems = client.listSubscriptionLineItems(subscriptionId, params); for (LineItem lineItem : lineItems) { System.out.println(lineItem.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $subscription_line_items = $client->listSubscriptionLineItems($subscription_id, $options); foreach($subscription_line_items as $line_item) { echo 'Subscription Invoice: ' . $line_item->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListSubscriptionLineItemsParams{\n\tSort: \ recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\nsubLineItems, err := client.ListSubscriptionLineItems(subID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor subLineItems.HasMore() {\n\terr := subLineItems.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, lineItem := range subLineItems.Data() {\n\t\tfmt.Printf(\"Subscription Line Item %3d: %s\\n\",\n\t\t\ti,\n\t\t\tlineItem.Id,\n\t\t)\n\t}\n}" "/subscriptions/{subscription_id}/coupon_redemptions": get: tags: - coupon_redemption operationId: list_subscription_coupon_redemptions summary: Show the coupon redemptions for a subscription description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/subscription_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" responses: '200': description: A list of the the coupon redemptions on a subscription. content: application/json: schema: "$ref": "#/components/schemas/CouponRedemptionList" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const redemptions = client.listSubscriptionCouponRedemptions(subscriptionId, { params: { limit: 200 } }) for await (const redemption of redemptions.each()) { console.log(redemption.id) } - lang: Python source: | params = {"limit": 200} redemptions = client.list_subscription_coupon_redemptions( subscription_id, params=params ).items() for redemption in redemptions: print(redemption.uuid) - lang: ".NET" source: | var subscriptionCouponRedemptions = client.ListSubscriptionCouponRedemptions(subscriptionId); foreach(CouponRedemption redemption in subscriptionCouponRedemptions) { Console.WriteLine(redemption.Id); } - lang: Ruby source: | params = { limit: 200 } coupon_redemptions = @client.list_subscription_coupon_redemptions( subscription_id: subscription_id, params: params ) coupon_redemptions.each do |redemption| puts "CouponRedemption: #{redemption.id}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager redemptions = client.listSubscriptionCouponRedemptions(subscriptionId, params); for (CouponRedemption redemption : redemptions) { System.out.println(redemption.getId()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $subscription_coupon_redemptions = $client->listSubscriptionCouponRedemptions($subscription_id, $options); foreach($subscription_coupon_redemptions as $redemption) { echo 'Subscription Coupon Redemption: ' . $redemption->getId() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListSubscriptionCouponRedemptionsParams{\n\tSort: recurly.String(\"created_at\"),\n}\nsubCouponRedemptions, err := client.ListSubscriptionCouponRedemptions(subID, listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor subCouponRedemptions.HasMore() {\n\terr := subCouponRedemptions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, redemption := range subCouponRedemptions.Data() {\n\t\tfmt.Printf(\"Subscription Coupon Redemption %3d: %s\\n\",\n\t\t\ti,\n\t\t\tredemption.Id,\n\t\t)\n\t}\n}" "/subscriptions/{subscription_id}/add_ons/{add_on_id}/usage": get: tags: - usage operationId: list_usage summary: List a subscription add-on's usage records parameters: - "$ref": "#/components/parameters/subscription_id" - "$ref": "#/components/parameters/add_on_id" - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/usage_sort_dates" - "$ref": "#/components/parameters/filter_usage_begin_time" - "$ref": "#/components/parameters/filter_usage_end_time" - "$ref": "#/components/parameters/billing_status" responses: '200': description: A list of the subscription add-on's usage records. content: application/json: schema: "$ref": "#/components/schemas/UsageList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID or add-on id. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] post: tags: - usage operationId: create_usage summary: Log a usage record on this subscription add-on parameters: - "$ref": "#/components/parameters/subscription_id" - "$ref": "#/components/parameters/add_on_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/UsageCreate" required: true responses: '201': description: The created usage record. content: application/json: schema: "$ref": "#/components/schemas/Usage" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID or add-on id. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/usage/{usage_id}": get: tags: - usage operationId: get_usage summary: Get a usage record parameters: - "$ref": "#/components/parameters/usage_id" responses: '200': description: The usage record. content: application/json: schema: "$ref": "#/components/schemas/Usage" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription, add-on, or usage ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] put: tags: - usage operationId: update_usage summary: Update a usage record parameters: - "$ref": "#/components/parameters/usage_id" requestBody: content: application/json: schema: "$ref": "#/components/schemas/UsageCreate" required: true responses: '200': description: The updated usage record. content: application/json: schema: "$ref": "#/components/schemas/Usage" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription, add-on, or usage ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] delete: tags: - usage operationId: remove_usage summary: Delete a usage record. parameters: - "$ref": "#/components/parameters/usage_id" responses: '204': description: Usage was successfully deleted. '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription, add-on, or usage ID. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: A validation error. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/transactions": get: tags: - transaction operationId: list_transactions summary: List a site's transactions description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/ids" - "$ref": "#/components/parameters/limit" - "$ref": "#/components/parameters/order" - "$ref": "#/components/parameters/sort_dates" - "$ref": "#/components/parameters/filter_begin_time" - "$ref": "#/components/parameters/filter_end_time" - "$ref": "#/components/parameters/filter_transaction_type" - "$ref": "#/components/parameters/filter_transaction_success" responses: '200': description: A list of the site's transactions. content: application/json: schema: "$ref": "#/components/schemas/TransactionList" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or subscription ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | const transactions = client.listTransactions({ params: { limit: 200 } }) for await (const transaction of transactions.each()) { console.log(transaction.uuid) } - lang: Python source: | params = {"limit": 200} transactions = client.list_transactions(params=params).items() for transaction in transactions: print(transaction.uuid) - lang: ".NET" source: | var optionalParams = new ListTransactionsParams() { Limit = 200 }; var transactions = client.ListTransactions(optionalParams); foreach(Transaction transaction in transactions) { Console.WriteLine(transaction.Uuid); } - lang: Ruby source: | params = { limit: 200 } transactions = @client.list_transactions(params: params) transactions.each do |transaction| puts "Transaction: #{transaction.uuid}" end - lang: Java source: | QueryParams params = new QueryParams(); params.setLimit(200); // Pull 200 records at a time final Pager transactions = client.listTransactions(params); for (Transaction transaction : transactions) { System.out.println(transaction.getUuid()); } - lang: PHP source: | $options = [ 'params' => [ 'limit' => 200 ] ]; $transactions = $client->listTransactions($options); foreach($transactions as $transaction) { echo 'Transaction: ' . $transaction->getUuid() . PHP_EOL; } - lang: Go source: "listParams := &recurly.ListTransactionsParams{\n\tSort: recurly.String(\"created_at\"),\n\tOrder: recurly.String(\"desc\"),\n\tLimit: recurly.Int(200),\n}\ntransactions, err := client.ListTransactions(listParams)\nif err != nil {\n\tfmt.Println(\"Unexpected error: %v\", err)\n\treturn\n}\n\nfor transactions.HasMore() {\n\terr := transactions.Fetch()\n\tif e, ok := err.(*recurly.Error); ok {\n\t\tfmt.Printf(\"Failed to retrieve next page: %v\", e)\n\t\tbreak\n\t}\n\tfor i, transaction := range transactions.Data() {\n\t\tfmt.Printf(\"Transaction %3d: %s\\n\",\n\t\t\ti,\n\t\t\ttransaction.Id,\n\t\t)\n\t}\n}" "/transactions/{transaction_id}": get: tags: - transaction operationId: get_transaction summary: Fetch a transaction parameters: - "$ref": "#/components/parameters/transaction_id" responses: '200': description: A transaction. content: application/json: schema: "$ref": "#/components/schemas/Transaction" '404': description: Incorrect site or transaction ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const transaction = await client.getTransaction(transactionId) console.log('Fetched transaction: ', transaction.uuid) } catch (err) { if (err instanceof recurly.errors.NotFoundError) { // If the request was not found, you may want to alert the user or // just return null console.log('Resource Not Found') } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: transaction = client.get_transaction(transaction_id) print("Got Transaction %s" % transaction) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { Transaction transaction = client.GetTransaction(transactionId); Console.WriteLine($"Fetched transaction {transaction.Uuid}"); } catch (Recurly.Errors.NotFound ex) { // If the resource was not found // we may want to alert the user or just return null Console.WriteLine($"Resource Not Found: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin transaction = @client.get_transaction(transaction_id: transaction_id) puts "Got Transaction #{transaction}" rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { Transaction transaction = client.getTransaction(transactionId); System.out.println("Fetched transaction " + transaction.getUuid()); } catch (NotFoundException e) { // If the resource was not found // we may want to alert the user or just return null System.out.println("Resource Not Found: " + e.getError().getMessage()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $transaction = $client->getTransaction($transaction_id); echo 'Got Transaction:' . PHP_EOL; var_dump($transaction); } catch (\Recurly\Errors\NotFound $e) { // Could not find the resource, you may want to inform the user // or just return a NULL echo 'Could not find resource.' . PHP_EOL; var_dump($e); } catch (\Recurly\RecurlyError $e) { // Something bad happened... tell the user so that they can fix it? echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "transaction, err := client.GetTransaction(transactionID)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeNotFound {\n\t\tfmt.Printf(\"Resource not found: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Fetched Transaction: %v\", transaction.Id)" "/unique_coupon_codes/{unique_coupon_code_id}": parameters: - "$ref": "#/components/parameters/unique_coupon_code_id" get: tags: - unique_coupon_code operationId: get_unique_coupon_code summary: Fetch a unique coupon code responses: '200': description: A unique coupon code. content: application/json: schema: "$ref": "#/components/schemas/UniqueCouponCode" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] delete: tags: - unique_coupon_code operationId: deactivate_unique_coupon_code summary: Deactivate a unique coupon code description: Expire a unique code, making that specific code no longer redeemable. The parent bulk coupon will not be affected. responses: '200': description: A unique coupon code. content: application/json: schema: "$ref": "#/components/schemas/UniqueCouponCode" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Unique coupon code cannot be deactivated for the provided reason. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/unique_coupon_codes/{unique_coupon_code_id}/restore": parameters: - "$ref": "#/components/parameters/unique_coupon_code_id" put: tags: - unique_coupon_code operationId: reactivate_unique_coupon_code summary: Restore a unique coupon code responses: '200': description: A unique coupon code. content: application/json: schema: "$ref": "#/components/schemas/UniqueCouponCode" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Unique coupon code cannot be restored for the provided reason. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/purchases": post: tags: - purchase operationId: create_purchase summary: Create a new purchase description: A purchase is a checkout containing at least one or more subscriptions or one-time charges (line items) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. requestBody: content: application/json: schema: "$ref": "#/components/schemas/PurchaseCreate" required: true responses: '201': description: Returns the new invoices content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollection" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Purchase cannot be completed for the specified reason. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let purchaseReq = { currency: 'USD', account: { code: accountCode, firstName: 'Benjamin', lastName: 'Du Monde', billingInfo: { tokenId: rjsTokenId } }, subscriptions: [ { planCode: planCode }, ] } let invoiceCollection = await client.createPurchase(purchaseReq) console.log('Created Charge Invoice: ', invoiceCollection.chargeInvoice) console.log('Created Credit Invoices: ', invoiceCollection.creditInvoices) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: purchase = { "currency": "USD", "account": { "code": account_code, "first_name": "Benjamin", "last_name": "Du Monde", "billing_info": {"token_id": rjs_token_id}, }, "subscriptions": [{"plan_code": plan_code}], } invoice_collection = client.create_purchase(purchase) print("Created Charge Invoice %s" % invoice_collection.charge_invoice) print("Created Credit Invoices %s" % invoice_collection.credit_invoices) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var purchaseReq = new PurchaseCreate() { Currency = "USD", Account = new AccountPurchase() { Code = accountCode, FirstName = "Benjamin", LastName = "Du Monde", BillingInfo = new BillingInfoCreate() { TokenId = rjsTokenId } }, Subscriptions = new List() { new SubscriptionPurchase() { PlanCode = planCode } } }; InvoiceCollection collection = client.CreatePurchase(purchaseReq); Console.WriteLine($"Created ChargeInvoice with Number: {collection.ChargeInvoice.Number}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin purchase = { currency: "USD", account: { code: account_code, first_name: "Benjamin", last_name: "Du Monde", billing_info: { token_id: rjs_token_id }, }, subscriptions: [ { plan_code: plan_code } ] } invoice_collection = @client.create_purchase( body: purchase ) puts "Created Charge Invoice #{invoice_collection.charge_invoice}" puts "Created Credit Invoices #{invoice_collection.credit_invoices}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { AccountPurchase account = new AccountPurchase(); account.setCode(accountCode); account.setFirstName("Benjamin"); account.setLastName("DuMonde"); BillingInfoCreate billing = new BillingInfoCreate(); billing.setTokenId(rjsTokenId); account.setBillingInfo(billing); List subscriptions = new ArrayList(); SubscriptionPurchase sub = new SubscriptionPurchase(); sub.setPlanCode(planCode); subscriptions.add(sub); PurchaseCreate purchase = new PurchaseCreate(); purchase.setCurrency("USD"); purchase.setAccount(account); purchase.setSubscriptions(subscriptions); InvoiceCollection collection = client.createPurchase(purchase); System.out.println("Created ChargeInvoice with Id: " + collection.getChargeInvoice().getId()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); System.out.println("Params: " + e.getError().getParams()); } catch (TransactionException e) { TransactionError tError = e.getError().getTransactionError(); if (tError.getCategory() == Constants.ErrorCategory.THREE_D_SECURE_ACTION_REQUIRED) { String actionTokenId = tError.getThreeDSecureActionTokenId(); System.out.println("Got 3DSecure TransactionError token: " + actionTokenId); } } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $purchase_create = [ "currency" => "USD", "account" => [ "code" => $account_code, "first_name" => "Douglas", "last_name" => "Du Monde", "billing_info" => [ "token_id" => $rjs_token_id ], ], "subscriptions" => [ [ "plan_code" => $plan_code ] ] ]; $invoice_collection = $client->createPurchase($purchase_create); echo 'Created Invoices:' . PHP_EOL; var_dump($invoice_collection); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "purchaseReq := &recurly.PurchaseCreate{\n\tCurrency: recurly.String(\"USD\"),\n\tAccount: &recurly.AccountPurchase{\n\t\tCode: recurly.String(accountCode),\n\t},\n\tSubscriptions: []recurly.SubscriptionPurchase{\n\t\t{\n\t\t\tPlanCode: recurly.String(planCode),\n\t\t\tNextBillDate: recurly.Time(time.Date(2078, time.November, 10, 23, 0, 0, 0, time.UTC)),\n\t\t},\n\t},\n\tShipping: &recurly.ShippingPurchase{\n\t\tAddressId: recurly.String(shippingAddressID),\n\t},\n}\n\ncollection, err := client.CreatePurchase(purchaseReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Created Purchase: %s\", collection.ChargeInvoice.Number)" "/purchases/preview": post: tags: - purchase operationId: preview_purchase summary: Preview a new purchase description: A purchase is a checkout containing at least one or more subscriptions or one-time charges (line items) and supports both coupon and gift card redemptions. All items purchased will be on one invoice and paid for with one transaction. requestBody: content: application/json: schema: "$ref": "#/components/schemas/PurchaseCreate" required: true responses: '200': description: Returns preview of the new invoices content: application/json: schema: "$ref": "#/components/schemas/InvoiceCollection" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Purchase cannot be previewed for the specified reason. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { let purchaseReq = { currency: 'USD', account: { firstName: 'Benjamin', lastName: 'Du Monde', code: accountCode, billingInfo: { tokenId: rjsTokenId } }, subscriptions: [ { planCode: planCode }, ] } let invoiceCollection = await client.previewPurchase(purchaseReq) console.log('Preview Charge Invoice: ', invoiceCollection.chargeInvoice) console.log('Preview Credit Invoices: ', invoiceCollection.creditInvoices) } catch (err) { if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params console.log('Failed validation', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it console.log('Unknown Error: ', err) } } - lang: Python source: | try: purchase = { "currency": "USD", "account": { "code": account_code, "first_name": "Benjamin", "last_name": "Du Monde", "billing_info": {"token_id": rjs_token_id}, }, "subscriptions": [{"plan_code": plan_code}], } invoice_collection = client.preview_purchase(purchase) print("Preview Charge Invoice %s" % invoice_collection.charge_invoice) print("Preview Credit Invoices %s" % invoice_collection.credit_invoices) except recurly.errors.ValidationError as e: # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.error.params print("ValidationError: %s" % e.error.message) print(e.error.params) - lang: ".NET" source: | try { var purchaseReq = new PurchaseCreate() { Currency = "USD", Account = new AccountPurchase() { Code = accountCode, FirstName = "Benjamin", LastName = "Du Monde", BillingInfo = new BillingInfoCreate() { TokenId = rjsTokenId } }, Subscriptions = new List() { new SubscriptionPurchase() { PlanCode = planCode } } }; InvoiceCollection collection = client.PreviewPurchase(purchaseReq); Console.WriteLine($"Preview ChargeInvoice with Total: {collection.ChargeInvoice.Total}"); } catch (Recurly.Errors.Validation ex) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in ex.Error.Params Console.WriteLine($"Failed validation: {ex.Error.Message}"); } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin purchase = { currency: "USD", account: { code: account_code, first_name: "Benjamin", last_name: "Du Monde", billing_info: { token_id: rjs_token_id }, }, subscriptions: [ { plan_code: plan_code } ] } invoice_collection = @client.preview_purchase( body: purchase ) puts "Preview Charge Invoice #{invoice_collection.charge_invoice}" puts "Preview Credit Invoices #{invoice_collection.credit_invoices}" rescue Recurly::Errors::ValidationError => e # If the request was invalid, you may want to tell your user # why. You can find the invalid params and reasons in e.recurly_error.params puts "ValidationError: #{e.recurly_error.params}" end - lang: Java source: | try { AccountPurchase account = new AccountPurchase(); account.setCode(accountCode); account.setFirstName("Joanna"); account.setLastName("DuMonde"); BillingInfoCreate billing = new BillingInfoCreate(); billing.setTokenId(rjsTokenId); account.setBillingInfo(billing); List subscriptions = new ArrayList(); SubscriptionPurchase sub = new SubscriptionPurchase(); sub.setPlanCode(planCode); subscriptions.add(sub); PurchaseCreate purchase = new PurchaseCreate(); purchase.setCurrency("USD"); purchase.setAccount(account); purchase.setSubscriptions(subscriptions); InvoiceCollection collection = client.previewPurchase(purchase); System.out.println("Preview Charge Invoice:" + collection.getChargeInvoice()); System.out.println("Preview Credit Invoices: " + collection.getCreditInvoices()); } catch (ValidationException e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in e.getError().getParams() System.out.println("Failed validation: " + e.getError().getMessage()); System.out.println("Params: " + e.getError().getParams()); } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $purchase_preview = [ "currency" => "USD", "account" => [ "code" => $account_code, "first_name" => "Douglas", "last_name" => "Du Monde", "billing_info" => [ "token_id" => $rjs_token_id ], ], "subscriptions" => [ [ "plan_code" => $plan_code ] ] ]; $invoice_collection = $client->previewPurchase($purchase_preview); echo 'Preview Invoices:' . PHP_EOL; var_dump($invoice_collection); } catch (\Recurly\Errors\Validation $e) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params var_dump($e); } catch (\Recurly\RecurlyError $e) { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it var_dump($e); } - lang: Go source: "collection, err := client.PreviewPurchase(purchaseReq)\nif e, ok := err.(*recurly.Error); ok {\n\tif e.Type == recurly.ErrorTypeValidation {\n\t\tfmt.Printf(\"Failed validation: %v\", e)\n\t\treturn nil, err\n\t}\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\nfmt.Printf(\"Preview Charge Invoice %v\", collection.ChargeInvoice)" "/export_dates": get: tags: - automated_exports operationId: get_export_dates summary: List the dates that have an available export to download. description: Returns a list of dates for which export files are available for download. responses: '200': description: Returns a list of dates. content: application/json: schema: "$ref": "#/components/schemas/ExportDates" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const export_dates = await client.getExportDates() export_dates.dates.forEach(date => { console.log(`Exports are available for: ${date}`) }) } catch (err) { if (err instanceof recurly.ApiError) { console.log('Unexpected error', err) } } - lang: Python source: | try: export_dates = client.get_export_dates() for date in export_dates.dates: print( "Exports are available for: %s" % date) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { ExportDates exportDates = client.GetExportDates(); foreach (var date in exportDates.Dates) { System.Console.WriteLine($"Exports are available for: {date}"); } } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin export_dates = @client.get_export_dates() export_dates.dates.each do |date| puts "Exports are available for: #{date}" end rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { ExportDates exportDates = client.getExportDates(); for (String date : exportDates.getDates()) { System.out.println("Exports are available for: " + date); } } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError().getMessage()); } - lang: PHP source: | try { $export_dates = $client->getExportDates(); foreach($export_dates->getDates() as $date) { echo "Exports are available for: {$date}" . PHP_EOL; } } catch (\Recurly\RecurlyError $e) { echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "exportDates, err := client.GetExportDates()\nif e, ok := err.(*recurly.Error); ok {\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfor _, date := range exportDates.Dates {\n\tfmt.Println(\"Exports are available for: \", date)\n}" "/export_dates/{export_date}/export_files": parameters: - "$ref": "#/components/parameters/export_date" get: tags: - automated_exports operationId: get_export_files summary: List of the export files that are available to download. description: Returns a list of presigned URLs to download export files for the given date, with their MD5 sums. responses: '200': description: Returns a list of export files to download. content: application/json: schema: "$ref": "#/components/schemas/ExportFiles" '400': description: Invalid or unpermitted parameter. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site ID or date. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: - lang: Node.js source: | try { const export_files = await client.getExportFiles(export_date) export_files.files.forEach(file => { console.log(`Export file download URL: ${file.href}`) }) } catch (err) { if (err instanceof recurly.ApiError) { console.log('Unexpected error', err) } } - lang: Python source: | try: export_files = client.get_export_files(export_date) for file in export_files.files: print( "Export file download URL: %s" % file.href) except recurly.errors.NotFoundError: # If the resource was not found, you may want to alert the user or # just return nil print("Resource Not Found") - lang: ".NET" source: | try { ExportFiles exportFiles = client.GetExportFiles(exportDate: exportDate); foreach (var file in exportFiles.Files) { System.Console.WriteLine($"Export file download URL: {file.Href}"); } } catch (Recurly.Errors.ApiError ex) { // Use ApiError to catch a generic error from the API Console.WriteLine($"Unexpected Recurly Error: {ex.Error.Message}"); } - lang: Ruby source: | begin export_files = @client.get_export_files(export_date: export_date) export_files.files.each do |file| puts "Export file download URL: #{file.href}" end rescue Recurly::Errors::NotFoundError # If the resource was not found, you may want to alert the user or # just return nil puts "Resource Not Found" end - lang: Java source: | try { ExportFiles exportFiles = client.getExportFiles(exportDate); for (ExportFile file : exportFiles.getFiles()) { System.out.println("Export file download URL: " + file.getHref()); } } catch (ApiException e) { // Use ApiException to catch a generic error from the API System.out.println("Unexpected Recurly Error: " + e.getError()); } - lang: PHP source: | try { $export_files = $client->getExportFiles($export_date); foreach($export_files->getFiles() as $file) { echo "Export file download URL: {$file->getHref()}" . PHP_EOL; } } catch (\Recurly\RecurlyError $e) { echo 'Some unexpected Recurly error happened. Try again later.' . PHP_EOL; } - lang: Go source: "exportFiles, err := client.GetExportFiles(exportDate)\nif e, ok := err.(*recurly.Error); ok {\n\tfmt.Printf(\"Unexpected Recurly error: %v\", e)\n\treturn nil, err\n}\n\nfor _, file := range exportFiles.Files {\n\tfmt.Println(\"Export file download URL: \", file.Href)\n}" "/dunning_campaigns": get: tags: - dunning_campaigns operationId: list_dunning_campaigns summary: Show the dunning campaigns for a site description: See the [Pagination Guide](/guides/pagination.html) to learn how to use pagination in the API and Client Libraries. parameters: - "$ref": "#/components/parameters/sort_dates" responses: '200': description: A list of the the dunning_campaigns on an account. content: application/json: schema: "$ref": "#/components/schemas/DunningCampaignList" '404': description: Incorrect site. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/dunning_campaigns/{dunning_campaign_id}": parameters: - "$ref": "#/components/parameters/dunning_campaign_id" get: tags: - dunning_campaigns operationId: get_dunning_campaign summary: Show the settings for a dunning campaign responses: '200': description: Settings for a dunning campaign. content: application/json: schema: "$ref": "#/components/schemas/DunningCampaign" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or campaign ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] "/dunning_campaigns/{dunning_campaign_id}/bulk_update": put: tags: - dunning_campaigns operationId: put_dunning_campaign_bulk_update summary: Assign a dunning campaign to multiple plans requestBody: content: application/json: schema: "$ref": "#/components/schemas/DunningCampaignsBulkUpdate" responses: '200': description: A list of updated plans. content: application/json: schema: "$ref": "#/components/schemas/DunningCampaignsBulkUpdateResponse" '400': description: Bad request; perhaps missing or invalid parameters. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Incorrect site or campaign ID. content: application/json: schema: "$ref": "#/components/schemas/Error" default: description: Unexpected error. content: application/json: schema: "$ref": "#/components/schemas/Error" x-code-samples: [] servers: - url: https://v3.recurly.com components: parameters: site_id: name: site_id in: path description: Site ID or subdomain. For ID no prefix is used e.g. `e28zov4fw0v2`. For subdomain use prefix `subdomain-`, e.g. `subdomain-recurly`. required: true schema: type: string account_id: name: account_id in: path description: Account ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-bob`. required: true schema: type: string add_on_id: name: add_on_id in: path description: Add-on ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-gold`. required: true schema: type: string billing_info_id: name: billing_info_id in: path description: Billing Info ID. required: true schema: type: string usage_id: name: usage_id in: path description: Usage Record ID. required: true schema: type: string coupon_id: name: coupon_id in: path description: Coupon ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-10off`. required: true schema: type: string credit_payment_id: name: credit_payment_id in: path description: Credit Payment ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`. required: true schema: type: string custom_field_definition_id: name: custom_field_definition_id in: path description: Custom Field Definition ID required: true schema: type: string item_id: name: item_id in: path description: Item ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-red`. required: true schema: type: string invoice_id: name: invoice_id in: path description: Invoice ID or number. For ID no prefix is used e.g. `e28zov4fw0v2`. For number use prefix `number-`, e.g. `number-1000`. required: true schema: type: string measured_unit_id: name: measured_unit_id in: path description: Measured unit ID or name. For ID no prefix is used e.g. `e28zov4fw0v2`. For name use prefix `name-`, e.g. `name-Storage`. required: true schema: type: string line_item_id: name: line_item_id in: path description: Line Item ID. required: true schema: type: string plan_id: name: plan_id in: path description: Plan ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-gold`. required: true schema: type: string shipping_address_id: name: shipping_address_id in: path description: Shipping Address ID. required: true schema: type: string shipping_method_id: name: shipping_method_id in: path description: Shipping Method ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-usps_2-day`. required: true schema: type: string subscription_id: name: subscription_id in: path description: Subscription ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`. required: true schema: type: string transaction_id: name: transaction_id in: path description: Transaction ID or UUID. For ID no prefix is used e.g. `e28zov4fw0v2`. For UUID use prefix `uuid-`, e.g. `uuid-123457890`. required: true schema: type: string unique_coupon_code_id: name: unique_coupon_code_id in: path description: Unique Coupon Code ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-abc-8dh2-def`. required: true schema: type: string dunning_campaign_id: name: dunning_campaign_id in: path description: Dunning Campaign ID, e.g. `e28zov4fw0v2`. required: true schema: type: string ids: name: ids in: query description: | Filter results by their IDs. Up to 200 IDs can be passed at once using commas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`. **Important notes:** * The `ids` parameter cannot be used with any other ordering or filtering parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc) * Invalid or unknown IDs will be ignored, so you should check that the results correspond to your request. * Records are returned in an arbitrary order. Since results are all returned at once you can sort the records yourself. style: form explode: false schema: type: array items: type: string limit: name: limit in: query description: Limit number of records 1-200. schema: type: integer minimum: 1 maximum: 200 default: 20 order: name: order in: query description: Sort order. schema: default: desc "$ref": "#/components/schemas/AlphanumericSortEnum" sort_dates: name: sort in: query description: | Sort field. You *really* only want to sort by `updated_at` in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned. schema: default: created_at "$ref": "#/components/schemas/TimestampSortEnum" usage_sort_dates: name: sort in: query description: | Sort field. You *really* only want to sort by `usage_timestamp` in ascending order. In descending order updated records will move behind the cursor and could prevent some records from being returned. schema: type: string "$ref": "#/components/schemas/UsageSortEnum" billing_status: name: billing_status in: query description: Filter by usage record's billing status schema: type: string "$ref": "#/components/schemas/BillingStatusEnum" filter_state: name: state in: query description: Filter by state. schema: "$ref": "#/components/schemas/ActiveStateEnum" filter_subscription_state: name: state in: query description: | Filter by state. - 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 `state=in_trial`, only subscriptions that have a trial_started_at date earlier than now and a trial_ends_at date later than now will be returned. - When `state=live`, only subscriptions that are in an active, canceled, or future state or are in trial will be returned. schema: "$ref": "#/components/schemas/FilterSubscriptionStateEnum" filter_begin_time: name: begin_time in: query description: | Inclusively filter by begin_time when `sort=created_at` or `sort=updated_at`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC. schema: type: string format: date-time filter_end_time: name: end_time in: query description: | Inclusively filter by end_time when `sort=created_at` or `sort=updated_at`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC. schema: type: string format: date-time filter_usage_begin_time: name: begin_time in: query description: | Inclusively filter by begin_time when `sort=usage_timestamp` or `sort=recorded_timestamp`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC. schema: type: string format: date-time filter_usage_end_time: name: end_time in: query description: | Inclusively filter by end_time when `sort=usage_timestamp` or `sort=recorded_timestamp`. **Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC. schema: type: string format: date-time filter_account_email: name: email in: query description: Filter for accounts with this exact email address. A blank value will return accounts with both `null` and `""` email addresses. Note that multiple accounts can share one email address. schema: type: string filter_account_subscriber: name: subscriber in: query description: | Filter for accounts with or without a subscription in the `active`, `canceled`, or `future` state. schema: type: boolean filter_account_past_due: name: past_due in: query description: Filter for accounts with an invoice in the `past_due` state. schema: "$ref": "#/components/schemas/TrueEnum" filter_line_item_original: name: original in: query description: Filter by original field. schema: "$ref": "#/components/schemas/TrueEnum" filter_line_item_state: name: state in: query description: Filter by state field. schema: "$ref": "#/components/schemas/LineItemStateEnum" filter_line_item_type: name: type in: query description: Filter by type field. schema: "$ref": "#/components/schemas/LineItemTypeEnum" filter_transaction_type: name: type in: query description: Filter by type field. The value `payment` will return both `purchase` and `capture` transactions. schema: "$ref": "#/components/schemas/FilterTransactionTypeEnum" filter_transaction_success: name: success in: query description: Filter by success field. schema: "$ref": "#/components/schemas/TrueEnum" filter_invoice_type: name: type in: query description: | Filter by type when: - `type=charge`, only charge invoices will be returned. - `type=credit`, only credit invoices will be returned. - `type=non-legacy`, only charge and credit invoices will be returned. - `type=legacy`, only legacy invoices will be returned. schema: "$ref": "#/components/schemas/FilterInvoiceTypeEnum" export_date: name: export_date in: path description: Date for which to get a list of available automated export files. Date must be in YYYY-MM-DD format. required: true schema: type: string securitySchemes: api_key: type: http description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page. scheme: basic schemas: Empty: type: object properties: {} BinaryFile: type: string format: binary readOnly: true AccountAcquisitionList: 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/AccountAcquisition" AccountList: 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/Account" AccountNoteList: 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/AccountNote" AddOnList: 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/AddOn" BillingInfoList: 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/BillingInfo" CreditPaymentList: 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/CreditPayment" CouponList: 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/Coupon" CouponRedemptionList: 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/CouponRedemption" 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" ItemList: 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/Item" InvoiceList: 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/Invoice" MeasuredUnitList: 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/MeasuredUnit" LineItemList: 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/LineItem" PlanList: 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/Plan" SiteList: 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/Site" ShippingMethodList: 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/ShippingMethod" SubscriptionList: 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/Subscription" TransactionList: 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/Transaction" Account: allOf: - "$ref": "#/components/schemas/AccountReadOnly" - "$ref": "#/components/schemas/AccountResponse" AccountAcquisition: allOf: - "$ref": "#/components/schemas/AccountAcquisitionUpdate" - "$ref": "#/components/schemas/AccountAcquisitionReadOnly" AccountAcquisitionUpdate: type: object properties: cost: type: object x-class-name: AccountAcquisitionCost title: Account balance items: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Amount description: The amount of the corresponding currency used to acquire the account. channel: description: The channel through which the account was acquired. "$ref": "#/components/schemas/ChannelEnum" subchannel: type: string description: An arbitrary subchannel string representing a distinction/subcategory within a broader channel. campaign: type: string description: An arbitrary identifier for the marketing campaign that led to the acquisition of this account. AccountAcquisitionReadOnly: type: object properties: id: type: string maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true account: "$ref": "#/components/schemas/AccountMini" created_at: type: string format: date-time description: When the account acquisition data was created. readOnly: true updated_at: type: string format: date-time description: When the account acquisition data was last changed. readOnly: true AccountReadOnly: type: object properties: id: type: string maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true state: description: Accounts can be either active or inactive. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" 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}`.' readOnly: true maxLength: 32 shipping_addresses: type: array description: The shipping addresses on the account. items: "$ref": "#/components/schemas/ShippingAddress" has_live_subscription: type: boolean description: Indicates if the account has a subscription that is either active, canceled, future, or paused. has_active_subscription: type: boolean description: Indicates if the account has an active subscription. has_future_subscription: type: boolean description: Indicates if the account has a future subscription. has_canceled_subscription: type: boolean description: Indicates if the account has a canceled subscription. has_paused_subscription: type: boolean description: Indicates if the account has a paused subscription. has_past_due_invoice: type: boolean description: Indicates if the account has a past due invoice. created_at: type: string format: date-time description: When the account was created. readOnly: true updated_at: type: string format: date-time description: When the account was last changed. readOnly: true deleted_at: type: string format: date-time description: If present, when the account was last marked inactive. readOnly: true AccountCreate: allOf: - type: object properties: code: type: string description: The unique identifier of the account. This cannot be changed once the account is created. maxLength: 50 acquisition: "$ref": "#/components/schemas/AccountAcquisitionUpdate" shipping_addresses: type: array items: "$ref": "#/components/schemas/ShippingAddressCreate" required: - code - "$ref": "#/components/schemas/AccountUpdate" AccountPurchase: allOf: - type: object properties: id: type: string description: Optional, but if present allows an existing account to be used and updated as part of the purchase. maxLength: 13 code: type: string description: The unique identifier of the account. This cannot be changed once the account is created. maxLength: 50 acquisition: "$ref": "#/components/schemas/AccountAcquisitionUpdate" required: - code - "$ref": "#/components/schemas/AccountUpdate" AccountUpdate: type: object properties: username: type: string description: A secondary value for the account. maxLength: 255 email: type: string format: email description: The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique. maxLength: 255 preferred_locale: 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. "$ref": "#/components/schemas/PreferredLocaleEnum" 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. maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 100 vat_number: type: string description: The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices. maxLength: 20 tax_exempt: type: boolean description: The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account. exemption_certificate: type: string description: The tax exemption certificate number for the account. If the merchant has an integration for the Vertex tax provider, this optional value will be sent in any tax calculation requests for the account. maxLength: 30 parent_account_code: type: string maxLength: 50 description: The account code of the parent account to be associated with this account. Passing an empty value removes any existing parent association from this account. If both `parent_account_code` and `parent_account_id` are passed, the non-blank value in `parent_account_id` will be used. Only one level of parent child relationship is allowed. You cannot assign a parent account that itself has a parent account. parent_account_id: type: string maxLength: 13 description: The UUID of the parent account to be associated with this account. Passing an empty value removes any existing parent association from this account. If both `parent_account_code` and `parent_account_id` are passed, the non-blank value in `parent_account_id` will be used. Only one level of parent child relationship is allowed. You cannot assign a parent account that itself has a parent account. bill_to: maxLength: 6 description: An enumerable describing the billing behavior of the account, specifically whether the account is self-paying or will rely on the parent account to pay. "$ref": "#/components/schemas/BillToEnum" transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" 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. address: "$ref": "#/components/schemas/Address" billing_info: "$ref": "#/components/schemas/BillingInfoCreate" custom_fields: "$ref": "#/components/schemas/CustomFields" AccountResponse: type: object properties: code: type: string description: The unique identifier of the account. This cannot be changed once the account is created. maxLength: 50 readOnly: true username: type: string description: A secondary value for the account. maxLength: 255 email: type: string format: email description: The email address used for communicating with this customer. The customer will also use this email address to log into your hosted account management pages. This value does not need to be unique. maxLength: 255 preferred_locale: description: Used to determine the language and locale of emails sent on behalf of the merchant to the customer. "$ref": "#/components/schemas/PreferredLocaleEnum" 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. maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 50 vat_number: type: string description: The VAT number of the account (to avoid having the VAT applied). This is only used for manually collected invoices. maxLength: 20 tax_exempt: type: boolean description: The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account. exemption_certificate: type: string description: The tax exemption certificate number for the account. If the merchant has an integration for the Vertex tax provider, this optional value will be sent in any tax calculation requests for the account. maxLength: 30 parent_account_id: type: string maxLength: 13 description: The UUID of the parent account associated with this account. bill_to: maxLength: 6 description: An enumerable describing the billing behavior of the account, specifically whether the account is self-paying or will rely on the parent account to pay. "$ref": "#/components/schemas/BillToEnum" 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. address: "$ref": "#/components/schemas/Address" billing_info: "$ref": "#/components/schemas/BillingInfo" custom_fields: "$ref": "#/components/schemas/CustomFields" AccountNote: type: object required: - message properties: id: type: string maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true account_id: type: string user: "$ref": "#/components/schemas/User" message: type: string created_at: type: string format: date-time readOnly: true AccountMini: type: object title: Account mini details properties: id: type: string maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string description: The unique identifier of the account. maxLength: 50 email: type: string format: email description: The email address used for communicating with this customer. maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 255 parent_account_id: type: string maxLength: 13 bill_to: type: string maxLength: 6 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. AccountBalance: type: object properties: object: type: string title: Object type readOnly: true account: "$ref": "#/components/schemas/AccountMini" past_due: type: boolean balances: type: array items: "$ref": "#/components/schemas/AccountBalanceAmount" AccountBalanceAmount: type: object title: Balance Amount properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Amount description: Total amount the account is past due. InvoiceAddress: allOf: - "$ref": "#/components/schemas/Address" - "$ref": "#/components/schemas/AddressWithName" type: object properties: name_on_account: type: string title: Name on account company: type: string title: Company Address: type: object properties: phone: type: string title: Phone number street1: type: string title: Street 1 street2: type: string title: Street 2 city: type: string title: City region: type: string title: State/Province description: State or province. postal_code: type: string title: Zip/Postal code description: Zip or postal code. country: type: string title: Country description: Country, 2-letter ISO 3166-1 alpha-2 code. AddressWithName: allOf: - "$ref": "#/components/schemas/Address" type: object properties: first_name: type: string title: First name last_name: type: string title: Last name AddOnMini: type: object title: Add-on mini details description: Just the important parts. properties: id: type: string title: Add-on ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Add-on code description: The unique identifier for the add-on within its plan. maxLength: 50 name: type: string title: Name description: Describes your add-on and will appear in subscribers' invoices. maxLength: 255 add_on_type: "$ref": "#/components/schemas/AddOnTypeEnum" usage_type: "$ref": "#/components/schemas/UsageTypeEnum" usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. measured_unit_id: type: string title: Measured Unit ID description: System-generated unique identifier for an measured unit associated with the add-on. maxLength: 13 item_id: type: string title: Item ID maxLength: 13 readOnly: true external_sku: type: string title: External SKU description: Optional, stock keeping unit to link the item to other inventory systems. maxLength: 50 readOnly: true accounting_code: type: string title: Accounting code description: Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 AddOn: type: object title: Add-on description: Full add-on details. properties: id: type: string title: Add-on ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true plan_id: type: string title: Plan ID maxLength: 13 readOnly: true code: type: string title: Add-on code description: The unique identifier for the add-on within its plan. maxLength: 50 state: title: State description: Add-ons can be either active or inactive. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" name: type: string title: Name description: Describes your add-on and will appear in subscribers' invoices. maxLength: 255 add_on_type: "$ref": "#/components/schemas/AddOnTypeEnum" usage_type: "$ref": "#/components/schemas/UsageTypeEnum" usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. measured_unit_id: type: string title: Measured Unit ID description: System-generated unique identifier for an measured unit associated with the add-on. maxLength: 13 accounting_code: type: string title: Accounting code description: Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type description: When this add-on is invoiced, the line item will use this revenue schedule. If `item_code`/`item_id` is part of the request then `revenue_schedule_type` must be absent in the request as the value will be set from the item. "$ref": "#/components/schemas/RevenueScheduleTypeEnum" avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 display_quantity: type: boolean title: Display quantity? description: Determines if the quantity field is displayed on the hosted pages for the add-on. default: false default_quantity: type: integer title: Default quantity description: Default quantity for the hosted pages. default: 1 optional: type: boolean title: Optional 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. currencies: type: array title: Add-on pricing items: "$ref": "#/components/schemas/AddOnPricing" minItems: 1 item: "$ref": "#/components/schemas/ItemMini" readOnly: true tier_type: "$ref": "#/components/schemas/TierTypeEnum" tiers: type: array title: Tiers items: "$ref": "#/components/schemas/Tier" external_sku: type: string title: External SKU description: Optional, stock keeping unit to link the item to other inventory systems. maxLength: 50 readOnly: true 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 readOnly: true required: - code - name AddOnCreate: type: object title: Add-on description: Full add-on details. properties: item_code: type: string title: Item Code description: Unique code to identify an item. Available when the `Credit Invoices` and `Subscription Billing Terms` features are enabled. If `item_id` and `item_code` are both present, `item_id` will be used. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 item_id: type: string title: Item ID description: System-generated unique identifier for an item. Available when the `Credit Invoices` and `Subscription Billing Terms` features are enabled. If `item_id` and `item_code` are both present, `item_id` will be used. maxLength: 13 code: type: string title: Add-on code description: The unique identifier for the add-on within its plan. If `item_code`/`item_id` is part of the request then `code` must be absent. If `item_code`/`item_id` is not present `code` is required. maxLength: 50 name: type: string title: Name description: Describes your add-on and will appear in subscribers' invoices. If `item_code`/`item_id` is part of the request then `name` must be absent. If `item_code`/`item_id` is not present `name` is required. maxLength: 255 add_on_type: "$ref": "#/components/schemas/AddOnTypeCreateEnum" usage_type: "$ref": "#/components/schemas/UsageTypeCreateEnum" usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if `add_on_type` is usage, `tier_type` is `flat` and `usage_type` is percentage. Must be omitted otherwise. measured_unit_id: type: string title: Measured Unit ID description: System-generated unique identifier for a measured unit to be associated with the add-on. Either `measured_unit_id` or `measured_unit_name` are required when `add_on_type` is `usage`. If `measured_unit_id` and `measured_unit_name` are both present, `measured_unit_id` will be used. maxLength: 13 measured_unit_name: type: string title: Measured Unit Name description: Name of a measured unit to be associated with the add-on. Either `measured_unit_id` or `measured_unit_name` are required when `add_on_type` is `usage`. If `measured_unit_id` and `measured_unit_name` are both present, `measured_unit_id` will be used. plan_id: type: string title: Plan ID maxLength: 13 readOnly: true accounting_code: type: string title: Accounting code description: Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. If `item_code`/`item_id` is part of the request then `accounting_code` must be absent. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type description: When this add-on is invoiced, the line item will use this revenue schedule. If `item_code`/`item_id` is part of the request then `revenue_schedule_type` must be absent in the request as the value will be set from the item. "$ref": "#/components/schemas/RevenueScheduleTypeEnum" display_quantity: type: boolean title: Display quantity? description: Determines if the quantity field is displayed on the hosted pages for the add-on. default: false default_quantity: type: integer title: Default quantity description: Default quantity for the hosted pages. default: 1 optional: type: boolean title: Optional 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. avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `AddOn`, then the `avalara_transaction_type` must be absent. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `AddOn`, then the `avalara_service_type` must be absent. minimum: 0 tax_code: type: string title: Tax code description: Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If `item_code`/`item_id` is part of the request then `tax_code` must be absent. maxLength: 50 currencies: type: array title: Add-on pricing items: "$ref": "#/components/schemas/AddOnPricing" minItems: 1 description: | * If `item_code`/`item_id` is part of the request and the item has a default currency then `currencies` is optional. If the item does not have a default currency, then `currencies` is required. If `item_code`/`item_id` is not present `currencies` is required. * If the add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `currencies` must be absent. * Must be absent if `add_on_type` is `usage` and `usage_type` is `percentage`. tier_type: "$ref": "#/components/schemas/TierTypeEnum" tiers: type: array title: Tiers items: "$ref": "#/components/schemas/Tier" 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` for the desired `currencies`, or alternatively, `usage_percentage` for usage percentage type usage add ons. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided. required: - code - name AddOnUpdate: type: object title: Add-on description: Full add-on details. properties: id: type: string title: Add-on ID maxLength: 13 readOnly: true code: type: string title: Add-on code description: The unique identifier for the add-on within its plan. If an `Item` is associated to the `AddOn` then `code` must be absent. maxLength: 50 name: type: string title: Name description: Describes your add-on and will appear in subscribers' invoices. If an `Item` is associated to the `AddOn` then `name` must be absent. maxLength: 255 usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if `add_on_type` is usage, `tier_type` is `flat` and `usage_type` is percentage. Must be omitted otherwise. measured_unit_id: type: string title: Measured Unit ID description: System-generated unique identifier for a measured unit to be associated with the add-on. Either `measured_unit_id` or `measured_unit_name` are required when `add_on_type` is `usage`. If `measured_unit_id` and `measured_unit_name` are both present, `measured_unit_id` will be used. maxLength: 13 measured_unit_name: type: string title: Measured Unit Name description: Name of a measured unit to be associated with the add-on. Either `measured_unit_id` or `measured_unit_name` are required when `add_on_type` is `usage`. If `measured_unit_id` and `measured_unit_name` are both present, `measured_unit_id` will be used. accounting_code: type: string title: Accounting code description: Accounting code for invoice line items for this add-on. If no value is provided, it defaults to add-on's code. If an `Item` is associated to the `AddOn` then `accounting code` must be absent. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type description: When this add-on is invoiced, the line item will use this revenue schedule. If `item_code`/`item_id` is part of the request then `revenue_schedule_type` must be absent in the request as the value will be set from the item. "$ref": "#/components/schemas/RevenueScheduleTypeEnum" avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `AddOn`, then the `avalara_transaction_type` must be absent. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the add-on is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `AddOn`, then the `avalara_service_type` must be absent. minimum: 0 tax_code: type: string title: Tax code description: Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. If an `Item` is associated to the `AddOn` then `tax code` must be absent. maxLength: 50 display_quantity: type: boolean title: Display quantity? description: Determines if the quantity field is displayed on the hosted pages for the add-on. default: false default_quantity: type: integer title: Default quantity description: Default quantity for the hosted pages. default: 1 optional: type: boolean title: Optional 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. currencies: type: array title: Add-on pricing items: "$ref": "#/components/schemas/AddOnPricing" minItems: 1 description: | If the add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then currencies must be absent. Must also be absent if `add_on_type` is `usage` and `usage_type` is `percentage`. tiers: type: array title: Tiers items: "$ref": "#/components/schemas/Tier" 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` for the desired `currencies`, or alternatively, `usage_percentage` for usage percentage type usage add ons. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided. BillingInfo: type: object properties: id: type: string maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true account_id: type: string maxLength: 13 readOnly: true first_name: type: string maxLength: 50 last_name: type: string maxLength: 50 company: type: string maxLength: 100 address: "$ref": "#/components/schemas/Address" vat_number: type: string description: Customer's VAT number (to avoid having the VAT applied). This is only used for automatically collected invoices. valid: type: boolean readOnly: true payment_method: "$ref": "#/components/schemas/PaymentMethod" fraud: type: object x-class-name: FraudInfo title: Fraud information description: Most recent fraud result. readOnly: true properties: score: type: integer title: Kount score minimum: 1 maximum: 99 decision: title: Kount decision maxLength: 10 "$ref": "#/components/schemas/KountDecisionEnum" risk_rules_triggered: type: object title: Kount rules primary_payment_method: type: boolean description: The `primary_payment_method` field is used to indicate the primary billing info on the account. The first billing info created on an account will always become primary. This payment method will be used backup_payment_method: type: boolean description: The `backup_payment_method` field is used to indicate a billing info as a backup on the account that will be tried if the initial billing info used for an invoice is declined. created_at: type: string format: date-time description: When the billing information was created. readOnly: true updated_at: type: string format: date-time description: When the billing information was last changed. readOnly: true updated_by: type: object x-class-name: BillingInfoUpdatedBy readOnly: true properties: ip: type: string description: Customer's IP address when updating their billing information. maxLength: 20 country: type: string description: Country, 2-letter ISO 3166-1 alpha-2 code matching the origin IP address, if known by Recurly. maxLength: 2 BillingInfoCreate: type: object properties: token_id: type: string title: Token ID description: A token [generated by Recurly.js](https://developers.recurly.com/reference/recurly-js/#getting-a-token). maxLength: 22 first_name: type: string title: First name maxLength: 50 last_name: type: string title: Last name maxLength: 50 company: type: string title: Company name maxLength: 100 address: "$ref": "#/components/schemas/Address" number: type: string title: Credit card number description: Credit card number, spaces and dashes are accepted. month: type: string title: Expiration month maxLength: 2 year: type: string title: Expiration year maxLength: 4 cvv: type: string title: Security code or CVV description: "*STRONGLY RECOMMENDED*" maxLength: 4 vat_number: type: string title: VAT number ip_address: type: string title: IP address description: "*STRONGLY RECOMMENDED* Customer's IP address when updating their billing information." maxLength: 20 gateway_token: type: string title: A token used in place of a credit card in order to perform transactions. Must be used in conjunction with `gateway_code`. maxLength: 50 gateway_code: type: string title: An identifier for a specific payment gateway. Must be used in conjunction with `gateway_token`. maxLength: 12 amazon_billing_agreement_id: type: string title: Amazon billing agreement ID paypal_billing_agreement_id: type: string title: PayPal billing agreement ID fraud_session_id: type: string title: Fraud Session ID transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" three_d_secure_action_result_token_id: type: string title: 3-D Secure action result token ID description: A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge. maxLength: 22 iban: type: string maxLength: 34 description: The International Bank Account Number, up to 34 alphanumeric characters comprising a country code; two check digits; and a number that includes the domestic bank account number, branch identifier, and potential routing information name_on_account: type: string maxLength: 255 description: The name associated with the bank account (ACH, SEPA, Bacs only) account_number: type: string maxLength: 255 description: The bank account number. (ACH, Bacs only) routing_number: type: string maxLength: 15 description: The bank's rounting number. (ACH only) sort_code: type: string maxLength: 15 description: Bank identifier code for UK based banks. Required for Bacs based billing infos. (Bacs only) type: "$ref": "#/components/schemas/AchTypeEnum" account_type: "$ref": "#/components/schemas/AchAccountTypeEnum" tax_identifier: type: string description: Tax identifier is required if adding a billing info that is a consumer card in Brazil or in Argentina. This would be the customer's CPF (Brazil) and CUIT (Argentina). CPF and CUIT are tax identifiers for all residents who pay taxes in Brazil and Argentina respectively. tax_identifier_type: description: This field and a value of `cpf` or `cuit` are required if adding a billing info that is an elo or hipercard type in Brazil or in Argentina. "$ref": "#/components/schemas/TaxIdentifierTypeEnum" primary_payment_method: type: boolean title: Primary Payment Method 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` with a value of `true`. 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 the initial billing info used for an invoice is declined. 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. BillingInfoVerify: type: object properties: gateway_code: type: string description: An identifier for a specific payment gateway. maxLength: 13 Coupon: type: object properties: id: type: string title: Coupon ID readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Coupon code description: The code the customer enters to redeem the coupon. name: type: string title: Name description: The internal name for the coupon. state: title: State description: Indicates if the coupon is redeemable, and if it is not, why. "$ref": "#/components/schemas/CouponStateEnum" max_redemptions: type: integer title: Max redemptions description: A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions. max_redemptions_per_account: type: integer title: Max redemptions per account description: Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign. unique_coupon_codes_count: type: integer title: Unique coupon codes count description: When this number reaches `max_redemptions` the coupon will no longer be redeemable. readOnly: true unique_code_template: type: string title: Unique code template description: On a bulk coupon, the template from which unique coupon codes are generated. unique_coupon_code: allOf: - "$ref": "#/components/schemas/UniqueCouponCode" type: object description: Will be populated when the Coupon being returned is a `UniqueCouponCode`. duration: title: Duration description: | - "single_use" coupons applies to the first invoice only. - "temporal" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes. "$ref": "#/components/schemas/CouponDurationEnum" temporal_amount: type: integer title: Temporal amount description: If `duration` is "temporal" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. temporal_unit: title: Temporal unit description: If `duration` is "temporal" than `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for. "$ref": "#/components/schemas/TemporalUnitEnum" free_trial_unit: title: Free trial unit description: Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for. "$ref": "#/components/schemas/FreeTrialUnitEnum" free_trial_amount: type: integer title: Free trial amount description: Sets the duration of time the `free_trial_unit` is for. minimum: 1 maximum: 9999 applies_to_all_plans: type: boolean title: Applies to all plans? description: The coupon is valid for all plans if true. If false then `plans` will list the applicable plans. default: true applies_to_all_items: type: boolean title: Applies to all items? description: | The coupon is valid for all items if true. If false then `items` will list the applicable items. default: false applies_to_non_plan_charges: type: boolean title: Applied to all non-plan charges? description: The coupon is valid for one-time, non-plan charges if true. default: false plans: type: array title: Plans description: A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`. items: "$ref": "#/components/schemas/PlanMini" items: type: array title: Items description: | A list of items for which this coupon applies. This will be `null` if `applies_to_all_items=true`. items: "$ref": "#/components/schemas/ItemMini" redemption_resource: title: Redemption resource description: Whether the discount is for all eligible charges on the account, or only a specific subscription. default: account "$ref": "#/components/schemas/RedemptionResourceEnum" discount: "$ref": "#/components/schemas/CouponDiscount" coupon_type: title: 'Coupon type (TODO: implement coupon generation)' 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. "$ref": "#/components/schemas/CouponTypeEnum" hosted_page_description: type: string title: Hosted Payment Pages description description: This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page. invoice_description: type: string title: Invoice description description: Description of the coupon on the invoice. maxLength: 255 redeem_by: type: string title: Redeem by description: The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. format: date-time created_at: type: string title: Created at format: date-time readOnly: true updated_at: type: string title: Last updated at format: date-time readOnly: true expired_at: type: string title: Expired at description: The date and time the coupon was expired early or reached its `max_redemptions`. format: date-time CouponCreate: allOf: - "$ref": "#/components/schemas/CouponUpdate" - type: object properties: code: type: string title: Coupon code description: The code the customer enters to redeem the coupon. discount_type: title: Discount type description: The type of discount provided by the coupon (how the amount discounted is calculated) "$ref": "#/components/schemas/DiscountTypeEnum" discount_percent: type: integer title: Discount percent description: The percent of the price discounted by the coupon. Required if `discount_type` is `percent`. free_trial_unit: title: Free trial unit description: Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for. Required if `discount_type` is `free_trial`. "$ref": "#/components/schemas/FreeTrialUnitEnum" free_trial_amount: type: integer title: Free trial amount description: Sets the duration of time the `free_trial_unit` is for. Required if `discount_type` is `free_trial`. minimum: 1 maximum: 9999 currencies: title: Currencies description: Fixed discount currencies by currency. Required if the coupon type is `fixed`. This parameter should contain the coupon discount values type: array items: "$ref": "#/components/schemas/CouponPricing" applies_to_non_plan_charges: type: boolean title: Applied to all non-plan charges? description: The coupon is valid for one-time, non-plan charges if true. default: false applies_to_all_plans: type: boolean title: Applies to all plans? description: The coupon is valid for all plans if true. If false then `plans` will list the applicable plans. default: true applies_to_all_items: type: boolean title: Applies to all items? description: | To apply coupon to Items in your Catalog, include a list of `item_codes` in the request that the coupon will apply to. Or set value to true to apply to all Items in your Catalog. The following values are not permitted when `applies_to_all_items` is included: `free_trial_amount` and `free_trial_unit`. default: false plan_codes: type: array title: Plan codes description: | List of plan codes to which this coupon applies. Required if `applies_to_all_plans` is false. Overrides `applies_to_all_plans` when `applies_to_all_plans` is true. items: type: string item_codes: type: array title: Item codes description: | List of item codes to which this coupon applies. Sending `item_codes` is only permitted when `applies_to_all_items` is set to false. The following values are not permitted when `item_codes` is included: `free_trial_amount` and `free_trial_unit`. items: type: string duration: title: Duration description: | This field does not apply when the discount_type is `free_trial`. - "single_use" coupons applies to the first invoice only. - "temporal" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes. - "forever" coupons will apply to invoices forever. default: forever "$ref": "#/components/schemas/CouponDurationEnum" temporal_amount: type: integer title: Temporal amount description: If `duration` is "temporal" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. temporal_unit: title: Temporal unit description: If `duration` is "temporal" than `temporal_unit` is multiplied by `temporal_amount` to define the duration that the coupon will be applied to invoices for. "$ref": "#/components/schemas/TemporalUnitEnum" coupon_type: title: Coupon type 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. "$ref": "#/components/schemas/CouponTypeEnum" unique_code_template: type: string title: Unique code template description: | On a bulk coupon, the template from which unique coupon codes are generated. - You must start the template with your coupon_code wrapped in single quotes. - Outside of single quotes, use a 9 for a character that you want to be a random number. - Outside of single quotes, use an "x" for a character that you want to be a random letter. - Outside of single quotes, use an * for a character that you want to be a random number or letter. - Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +. For example: "'abc-'****'-def'" redemption_resource: title: Redemption resource description: Whether the discount is for all eligible charges on the account, or only a specific subscription. default: account "$ref": "#/components/schemas/RedemptionResourceEnum" required: - code - discount_type - name CouponPricing: type: object properties: currency: type: string description: 3-letter ISO 4217 currency code. discount: type: number format: float description: The fixed discount (in dollars) for the corresponding currency. CouponDiscount: type: object description: | Details of the discount a coupon applies. Will contain a `type` property and one of the following properties: `percent`, `fixed`, `trial`. properties: type: "$ref": "#/components/schemas/DiscountTypeEnum" percent: description: This is only present when `type=percent`. type: integer currencies: type: array description: This is only present when `type=fixed`. items: "$ref": "#/components/schemas/CouponDiscountPricing" trial: type: object x-class-name: CouponDiscountTrial description: This is only present when `type=free_trial`. properties: unit: title: Trial unit description: Temporal unit of the free trial "$ref": "#/components/schemas/FreeTrialUnitEnum" length: type: integer title: Trial length description: Trial length measured in the units specified by the sibling `unit` property CouponDiscountPricing: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Discount Amount description: Value of the fixed discount that this coupon applies. CouponBulkCreate: type: object properties: number_of_unique_codes: type: integer title: Number of unique codes description: The quantity of unique coupon codes to generate minimum: 1 maximum: 200 CouponMini: type: object properties: id: type: string title: Coupon ID readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Coupon code description: The code the customer enters to redeem the coupon. name: type: string title: Name description: The internal name for the coupon. state: title: State description: Indicates if the coupon is redeemable, and if it is not, why. "$ref": "#/components/schemas/CouponStateEnum" discount: "$ref": "#/components/schemas/CouponDiscount" coupon_type: title: 'Coupon type (TODO: implement coupon generation)' 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. "$ref": "#/components/schemas/CouponTypeEnum" expired_at: type: string title: Expired at description: The date and time the coupon was expired early or reached its `max_redemptions`. format: date-time CouponRedemption: type: object properties: id: type: string title: Coupon Redemption ID readOnly: true object: type: string title: Object type description: Will always be `coupon`. readOnly: true account: type: object title: Account description: The Account on which the coupon was applied. readOnly: true "$ref": "#/components/schemas/AccountMini" subscription_id: type: string title: Subscription ID readOnly: true coupon: "$ref": "#/components/schemas/Coupon" state: title: Coupon Redemption state default: active "$ref": "#/components/schemas/ActiveStateEnum" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 discounted: type: number format: float title: Amount Discounted description: The amount that was discounted upon the application of the coupon, formatted with the currency. created_at: type: string title: Created at format: date-time readOnly: true updated_at: type: string title: Last updated at format: date-time readOnly: true removed_at: type: string title: Removed at description: The date and time the redemption was removed from the account (un-redeemed). format: date-time CouponRedemptionCreate: type: object properties: coupon_id: type: string title: Coupon ID currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 subscription_id: type: string title: Subscription ID required: - coupon_id CouponRedemptionMini: type: object properties: id: type: string title: Coupon Redemption ID readOnly: true object: type: string title: Object type description: Will always be `coupon`. readOnly: true coupon: "$ref": "#/components/schemas/CouponMini" state: title: Invoice state "$ref": "#/components/schemas/ActiveStateEnum" discounted: type: number format: float title: Amount Discounted description: The amount that was discounted upon the application of the coupon, formatted with the currency. created_at: type: string title: Created at format: date-time readOnly: true CouponUpdate: type: object properties: name: type: string title: Name description: The internal name for the coupon. max_redemptions: type: integer title: Max redemptions description: A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions. max_redemptions_per_account: type: integer title: Max redemptions per account description: Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign. hosted_description: type: string title: Hosted Payment Pages description description: This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page. invoice_description: type: string title: Invoice description description: Description of the coupon on the invoice. maxLength: 255 redeem_by_date: type: string title: Redeem by description: The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time. CreditPayment: type: object properties: id: type: string title: Credit Payment ID maxLength: 13 object: type: string title: Object type uuid: type: string title: Recurly UUID description: The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI. maxLength: 32 action: title: Action description: The action for which the credit was created. "$ref": "#/components/schemas/CreditPaymentActionEnum" account: "$ref": "#/components/schemas/AccountMini" applied_to_invoice: "$ref": "#/components/schemas/InvoiceMini" original_invoice: "$ref": "#/components/schemas/InvoiceMini" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Amount description: Total credit payment amount applied to the charge invoice. original_credit_payment_id: type: string title: Original Credit Payment ID description: For credit payments with action `refund`, this is the credit payment that was refunded. maxLength: 13 refund_transaction: "$ref": "#/components/schemas/Transaction" created_at: type: string title: Created at format: date-time readOnly: true updated_at: type: string title: Last updated at format: date-time readOnly: true voided_at: type: string title: Voided at format: date-time readOnly: true CustomField: type: object title: Custom field properties: name: type: string title: Field name description: Fields must be created in the UI before values can be assigned to them. pattern: "/^[a-z0-9_-]+$/i" maxLength: 50 value: type: string title: Field value description: Any values that resemble a credit card number or security code (CVV/CVC) will be rejected. maxLength: 100 required: - name - value CustomFields: type: array 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. items: "$ref": "#/components/schemas/CustomField" 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. "$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 ItemMini: type: object title: Item mini details description: Just the important parts. properties: id: type: string title: Item ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Item code description: Unique code to identify the item. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 state: title: State description: The current state of the item. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" name: type: string title: Name description: This name describes your item and will appear on the invoice when it's purchased on a one time basis. maxLength: 255 description: type: string title: Description description: Optional, description. Item: type: object description: Full item details. properties: id: type: string title: Item ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Item code description: Unique code to identify the item. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 state: title: State description: The current state of the item. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" name: type: string title: Name description: This name describes your item and will appear on the invoice when it's purchased on a one time basis. maxLength: 255 description: type: string title: Description description: Optional, description. external_sku: type: string title: External SKU description: Optional, stock keeping unit to link the item to other inventory systems. maxLength: 50 accounting_code: type: string title: Item accounting code description: Accounting code for invoice line items. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the item, `false` applies tax on the item." custom_fields: "$ref": "#/components/schemas/CustomFields" currencies: type: array title: Item Pricing items: "$ref": "#/components/schemas/Pricing" 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 readOnly: true ItemCreate: type: object properties: code: type: string title: Item code description: Unique code to identify the item. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 name: type: string title: Name description: This name describes your item and will appear on the invoice when it's purchased on a one time basis. maxLength: 255 description: type: string title: Description description: Optional, description. external_sku: type: string title: External SKU description: Optional, stock keeping unit to link the item to other inventory systems. maxLength: 50 accounting_code: type: string title: Item accounting code description: Accounting code for invoice line items. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the item, `false` applies tax on the item." custom_fields: "$ref": "#/components/schemas/CustomFields" currencies: type: array title: Item Pricing items: "$ref": "#/components/schemas/Pricing" required: - code - name ItemUpdate: type: object properties: code: type: string title: Item code description: Unique code to identify the item. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 name: type: string title: Name description: This name describes your item and will appear on the invoice when it's purchased on a one time basis. maxLength: 255 description: type: string title: Description description: Optional, description. external_sku: type: string title: External SKU description: Optional, stock keeping unit to link the item to other inventory systems. maxLength: 50 accounting_code: type: string title: Item accounting code description: Accounting code for invoice line items. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the item, `false` applies tax on the item." custom_fields: "$ref": "#/components/schemas/CustomFields" currencies: type: array title: Item Pricing items: "$ref": "#/components/schemas/Pricing" Invoice: type: object properties: id: type: string title: Invoice ID readOnly: true object: type: string title: Object type readOnly: true type: title: Invoice type description: Invoices are either charge, credit, or legacy invoices. "$ref": "#/components/schemas/InvoiceTypeEnum" origin: title: Origin description: The event that created the invoice. "$ref": "#/components/schemas/OriginEnum" state: title: Invoice state "$ref": "#/components/schemas/InvoiceStateEnum" account: "$ref": "#/components/schemas/AccountMini" billing_info_id: type: string title: Billing info ID description: The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. subscription_ids: type: array title: Subscription IDs description: If the invoice is charging or refunding for one or more subscriptions, these are their IDs. items: type: string title: Subscription ID maxLength: 13 previous_invoice_id: type: string title: Previous invoice ID description: On refund invoices, this value will exist and show the invoice ID of the purchase invoice the refund was created from. maxLength: 13 number: type: string title: Invoice number description: 'If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.' collection_method: title: Collection method description: An automatic invoice means a corresponding transaction is run using the account's billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction. The merchant must enter a manual payment transaction or have the customer pay the invoice with an automatic method, like credit card, PayPal, Amazon, or ACH bank payment. default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 address: "$ref": "#/components/schemas/InvoiceAddress" shipping_address: "$ref": "#/components/schemas/ShippingAddress" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 discount: type: number format: float title: Discount description: Total discounts applied to this invoice. subtotal: type: number format: float title: Subtotal description: The summation of charges and credits, before discounts and taxes. tax: type: number format: float title: Tax description: The total tax on this invoice. total: type: number format: float title: Total description: The final total on this invoice. The summation of invoice charges, discounts, credits, and tax. refundable_amount: type: number format: float title: Refundable amount description: The refundable amount on a charge invoice. It will be null for all other invoices. paid: type: number format: float title: Paid description: The total amount of successful payments transaction on this invoice. balance: type: number format: float title: Balance description: The outstanding balance remaining on this invoice. tax_info: "$ref": "#/components/schemas/TaxInfo" vat_number: type: string title: VAT number description: VAT registration number for the customer on this invoice. This will come from the VAT Number field in the Billing Info or the Account Info depending on your tax settings and the invoice collection method. maxLength: 20 vat_reverse_charge_notes: type: string title: VAT reverse charge notes 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. terms_and_conditions: type: string title: Terms and conditions description: This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions. customer_notes: type: string title: Customer notes description: This will default to the Customer Notes text specified on the Invoice Settings. Specify custom notes to add or override Customer Notes. line_items: type: array title: Line Items items: "$ref": "#/components/schemas/LineItem" has_more_line_items: type: boolean title: Has more Line Items description: Identifies if the invoice has more line items than are returned in `line_items`. If `has_more_line_items` is `true`, then a request needs to be made to the `list_invoice_line_items` endpoint. transactions: type: array title: Transactions items: "$ref": "#/components/schemas/Transaction" credit_payments: type: array title: Credit payments items: "$ref": "#/components/schemas/CreditPayment" 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 due_at: type: string format: date-time title: Due at description: Date invoice is due. This is the date the net terms are reached. closed_at: type: string format: date-time title: Closed at description: Date invoice was marked paid or failed. dunning_campaign_id: type: string title: Dunning Campaign ID description: Unique ID to identify the dunning campaign used when dunning the invoice. Available when the Dunning Campaigns feature is enabled. For sites without multiple dunning campaigns enabled, this will always be the default dunning campaign. InvoiceCreate: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 collection_method: title: Collection method description: An automatic invoice means a corresponding transaction is run using the account's billing information at the same time the invoice is created. Manual invoices are created without a corresponding transaction. The merchant must enter a manual payment transaction or have the customer pay the invoice with an automatic method, like credit card, PayPal, Amazon, or ACH bank payment. default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" charge_customer_notes: type: string title: Charge customer notes description: This will default to the Customer Notes text specified on the Invoice Settings for charge invoices. Specify custom notes to add or override Customer Notes on charge invoices. credit_customer_notes: type: string title: Credit customer notes description: This will default to the Customer Notes text specified on the Invoice Settings for credit invoices. Specify customer notes to add or override Customer Notes on credit invoices. net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. default: 0 minimum: 0 po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 terms_and_conditions: type: string title: Terms and conditions description: This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions. vat_reverse_charge_notes: type: string title: VAT reverse charge notes 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. required: - currency InvoiceCollect: type: object properties: three_d_secure_action_result_token_id: type: string title: 3-D Secure action result token ID description: A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge. maxLength: 22 transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" billing_info_id: type: string title: Billing Info ID description: The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. InvoiceCollection: type: object title: Invoice collection properties: object: type: string title: Object type charge_invoice: "$ref": "#/components/schemas/Invoice" credit_invoices: type: array title: Credit invoices items: "$ref": "#/components/schemas/Invoice" InvoiceUpdate: type: object properties: po_number: type: string title: Purchase order number description: This identifies the PO number associated with the invoice. Not editable for credit invoices. maxLength: 50 vat_reverse_charge_notes: type: string title: VAT reverse charge notes description: VAT Reverse Charge Notes are editable only if there was a VAT reverse charge applied to the invoice. terms_and_conditions: type: string title: Terms and conditions description: Terms and conditions are an optional note field. Not editable for credit invoices. customer_notes: type: string title: Customer notes description: Customer notes are an optional note field. net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. Changing Net terms changes due_on, and the invoice could move between past due and pending. minimum: 0 maximum: 999 address: "$ref": "#/components/schemas/InvoiceAddress" InvoiceMini: type: object title: Invoice mini details properties: id: type: string title: Invoice ID maxLength: 13 object: type: string title: Object type number: type: string title: Invoice number type: title: Invoice type "$ref": "#/components/schemas/InvoiceTypeEnum" state: title: Invoice state "$ref": "#/components/schemas/InvoiceStateEnum" InvoiceRefund: type: object title: Invoice refund properties: type: title: Type description: The type of refund. Amount and line items cannot both be specified in the request. "$ref": "#/components/schemas/InvoiceRefundTypeEnum" amount: type: number format: float title: Amount description: | The amount to be refunded. The amount will be split between the line items. If no amount is specified, it will default to refunding the total refundable amount on the invoice. line_items: type: array title: Line items description: The line items to be refunded. This is required when `type=line_items`. items: "$ref": "#/components/schemas/LineItemRefund" refund_method: title: Refund method description: | Indicates how the invoice should be refunded when both a credit and transaction are present on the invoice: - `transaction_first` – Refunds the transaction first, then any amount is issued as credit back to the account. Default value when Credit Invoices feature is enabled. - `credit_first` – Issues credit back to the account first, then refunds any remaining amount back to the transaction. Default value when Credit Invoices feature is not enabled. - `all_credit` – Issues credit to the account for the entire amount of the refund. Only available when the Credit Invoices feature is enabled. - `all_transaction` – Refunds the entire amount back to transactions, using transactions from previous invoices if necessary. Only available when the Credit Invoices feature is enabled. default: credit_first "$ref": "#/components/schemas/RefuneMethodEnum" credit_customer_notes: type: string title: Credit customer notes description: | Used as the Customer Notes on the credit invoice. This field can only be include when the Credit Invoices feature is enabled. external_refund: type: object x-class-name: ExternalRefund description: | Indicates that the refund was settled outside of Recurly, and a manual transaction should be created to track it in Recurly. Required when: - refunding a manually collected charge invoice, and `refund_method` is not `all_credit` - refunding a credit invoice that refunded manually collecting invoices - refunding a credit invoice for a partial amount This field can only be included when the Credit Invoices feature is enabled. properties: payment_method: title: Payment Method description: Payment method used for external refund transaction. "$ref": "#/components/schemas/ExternalPaymentMethodEnum" description: type: string title: Description description: Used as the refund transactions' description. maxLength: 50 refunded_at: type: string format: date-time title: Refunded At description: Date the external refund payment was made. Defaults to the current date-time. required: - payment_method required: - type MeasuredUnit: type: object title: Measured unit properties: id: type: string title: Item ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true name: type: string title: Name description: Unique internal name of the measured unit on your site. display_name: type: string title: Display name description: Display name for the measured unit. Can only contain spaces, underscores and must be alphanumeric. maxLength: 50 state: title: State description: The current state of the measured unit. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" description: type: string title: Description description: Optional internal description. 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 readOnly: true MeasuredUnitCreate: type: object properties: name: type: string title: Name description: Unique internal name of the measured unit on your site. maxLength: 255 display_name: type: string title: Display name description: Display name for the measured unit. pattern: "/^[\\w ]+$/" maxLength: 50 description: type: string title: Description description: Optional internal description. required: - name - display_name MeasuredUnitUpdate: type: object properties: name: type: string title: Name description: Unique internal name of the measured unit on your site. maxLength: 255 display_name: type: string title: Display name description: Display name for the measured unit. pattern: "/^[\\w ]+$/" maxLength: 50 description: type: string title: Description description: Optional internal description. LineItem: type: object title: Line item properties: id: type: string title: Line item ID maxLength: 13 object: type: string title: Object type 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 type: title: Line item type description: Charges are positive line items that debit the account. Credits are negative line items that credit the account. "$ref": "#/components/schemas/LineItemTypeEnum" item_code: type: string title: Item Code description: Unique code to identify an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 item_id: type: string title: Item ID description: System-generated unique identifier for an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled. maxLength: 13 external_sku: type: string title: External SKU description: Optional Stock Keeping Unit assigned to an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled. maxLength: 50 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/LineItemRevenueScheduleTypeEnum" state: title: Current state of the line item description: Pending line items are charges or credits on an account that have not been applied to an invoice yet. Invoiced line items will always have an `invoice_id` value. "$ref": "#/components/schemas/LineItemStateEnum" legacy_category: title: Legacy category description: | Category to describe the role of a line item on a legacy invoice: - "charges" refers to charges being billed for on this invoice. - "credits" refers to refund or proration credits. This portion of the invoice can be considered a credit memo. - "applied_credits" refers to previous credits applied to this invoice. See their original_line_item_id to determine where the credit first originated. - "carryforwards" can be ignored. They exist to consume any remaining credit balance. A new credit with the same amount will be created and placed back on the account. "$ref": "#/components/schemas/LegacyCategoryEnum" account: "$ref": "#/components/schemas/AccountMini" bill_for_account_id: type: string title: Bill For Account ID maxLength: 13 description: The UUID of the account responsible for originating the line item. subscription_id: type: string title: Subscription ID description: If the line item is a charge or credit for a subscription, this is its ID. maxLength: 13 plan_id: type: string title: Plan ID description: If the line item is a charge or credit for a plan or add-on, this is the plan's ID. maxLength: 13 plan_code: type: string title: Plan code description: If the line item is a charge or credit for a plan or add-on, this is the plan's code. maxLength: 50 add_on_id: type: string title: Add-on ID description: If the line item is a charge or credit for an add-on this is its ID. maxLength: 13 add_on_code: type: string title: Add-on code description: If the line item is a charge or credit for an add-on, this is its code. maxLength: 50 invoice_id: type: string title: Invoice ID description: Once the line item has been invoiced this will be the invoice's ID. maxLength: 13 invoice_number: type: string title: Invoice number description: 'Once the line item has been invoiced this will be the invoice''s number. If VAT taxation and the Country Invoice Sequencing feature are enabled, invoices will have country-specific invoice numbers for invoices billed to EU countries (ex: FR1001). Non-EU invoices will continue to use the site-level invoice number sequence.' previous_line_item_id: type: string title: Previous line item ID description: Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund. maxLength: 13 original_line_item_invoice_id: type: string title: Original line item's invoice ID description: The invoice where the credit originated. Will only have a value if the line item is a credit created from a previous credit, or if the credit was created from a charge refund. maxLength: 13 origin: title: Origin of line item description: A credit created from an original charge will have the value of the charge's origin. "$ref": "#/components/schemas/LineItemOriginEnum" accounting_code: type: string title: Accounting code description: Internal accounting code to help you reconcile your revenue to the correct ledger. Line items created as part of a subscription invoice will use the plan or add-on's accounting code, otherwise the value will only be present if you define an accounting code when creating the line item. maxLength: 20 product_code: type: string title: Product code 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. For item-related line items it will be the item's `external_sku`. maxLength: 50 credit_reason_code: title: Credit reason code description: The reason the credit was given when line item is `type=credit`. default: general "$ref": "#/components/schemas/FullCreditReasonCodeEnum" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Total after discounts and taxes description: "`(quantity * unit_amount) - (discount + tax)`" description: type: string title: Description description: Description that appears on the invoice. For subscription related items this will be filled in automatically. maxLength: 255 quantity: type: integer title: Quantity description: This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes. default: 1 unit_amount: type: number format: float title: Unit amount description: Positive amount for a charge, negative amount for a credit. unit_amount_decimal: type: string title: Unit amount decimal description: Positive amount for a charge, negative amount for a credit. subtotal: type: number format: float title: Total before discounts and taxes description: "`quantity * unit_amount`" discount: type: number format: float title: Discount description: The discount applied to the line item. tax: type: number format: float title: Tax description: The tax amount for the line item. taxable: type: boolean title: Taxable? description: "`true` if the line item is taxable, `false` if it is not." tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on charges, `false` applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature." avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 tax_info: "$ref": "#/components/schemas/TaxInfo" proration_rate: type: number format: float title: Proration rate description: When a line item has been prorated, this is the rate of the proration. Proration rates were made available for line items created after March 30, 2017. For line items created prior to that date, the proration rate will be `null`, even if the line item was prorated. minimum: 0 maximum: 1 refund: type: boolean title: Refund? refunded_quantity: type: integer title: Refunded Quantity description: For refund charges, the quantity being refunded. For non-refund charges, the total quantity refunded (possibly over multiple refunds). credit_applied: type: number format: float title: Credit Applied description: The amount of credit from this line item that was applied to the invoice. shipping_address: "$ref": "#/components/schemas/ShippingAddress" start_date: type: string format: date-time title: Start date description: If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date. end_date: type: string format: date-time title: End date description: If this date is provided, it indicates the end of a time range. created_at: type: string format: date-time title: Created at description: When the line item was created. updated_at: type: string format: date-time title: Last updated at description: When the line item was last changed. LineItemRefund: type: object properties: id: type: string title: Line item ID maxLength: 13 quantity: type: integer title: Quantity description: Line item quantity to be refunded. prorate: type: boolean title: Prorate description: | Set to `true` if the line item should be prorated; set to `false` if not. This can only be used on line items that have a start and end date. default: false LineItemCreate: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. If `item_code`/`item_id` is part of the request then `currency` is optional, if the site has a single default currency. `currency` is required if `item_code`/`item_id` is present, and there are multiple currencies defined on the site. If `item_code`/`item_id` is not present `currency` is required. maxLength: 3 unit_amount: type: number format: float title: Unit amount description: | A positive or negative amount with `type=charge` will result in a positive `unit_amount`. A positive or negative amount with `type=credit` will result in a negative `unit_amount`. If `item_code`/`item_id` is present, `unit_amount` can be passed in, to override the `Item`'s `unit_amount`. If `item_code`/`item_id` is not present then `unit_amount` is required. quantity: type: integer title: Quantity description: This number will be multiplied by the unit amount to compute the subtotal before any discounts or taxes. default: 1 description: type: string title: Description description: Description that appears on the invoice. If `item_code`/`item_id` is part of the request then `description` must be absent. maxLength: 255 item_code: type: string title: Item Code description: Unique code to identify an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled. pattern: "/^[a-z0-9_+-]+$/" maxLength: 50 item_id: type: string title: Item ID description: System-generated unique identifier for an item. Available when the Credit Invoices and Subscription Billing Terms features are enabled. maxLength: 13 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/LineItemRevenueScheduleTypeEnum" type: title: Type description: Line item type. If `item_code`/`item_id` is present then `type` should not be present. If `item_code`/`item_id` is not present then `type` is required. "$ref": "#/components/schemas/LineItemTypeEnum" credit_reason_code: title: Credit reason code description: The reason the credit was given when line item is `type=credit`. When the Credit Invoices feature is enabled, the value can be set and will default to `general`. When the Credit Invoices feature is not enabled, the value will always be `null`. default: general "$ref": "#/components/schemas/PartialCreditReasonCodeEnum" accounting_code: type: string title: Accounting Code description: Accounting Code for the `LineItem`. If `item_code`/`item_id` is part of the request then `accounting_code` must be absent. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on charges, `false` applies tax on charges. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative line items). Credits are always applied post-tax. Pre-tax discounts should use the Coupons feature." avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `LineItem`, then the `avalara_transaction_type` must be absent. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the line item is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. If an `Item` is associated to the `LineItem`, then the `avalara_service_type` must be absent. minimum: 0 tax_code: type: string title: Tax code description: Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. maxLength: 50 product_code: type: string title: Product code description: Optional field to track a product code or SKU for the line item. This can be used to later reporting on product purchases. For Vertex tax calculations, this field will be used as the Vertex `product` field. If `item_code`/`item_id` is part of the request then `product_code` must be absent. maxLength: 50 origin: title: Origin description: Origin `external_gift_card` is allowed if the Gift Cards feature is enabled on your site and `type` is `credit`. Set this value in order to track gift card credits from external gift cards (like InComm). It also skips billing information requirements. Origin `prepayment` is only allowed if `type` is `charge` and `tax_exempt` is left blank or set to true. This origin creates a charge and opposite credit on the account to be used for future invoices. "$ref": "#/components/schemas/LineItemCreateOriginEnum" start_date: type: string format: date-time title: Start date description: If an end date is present, this is value indicates the beginning of a billing time range. If no end date is present it indicates billing for a specific date. Defaults to the current date-time. end_date: type: string format: date-time title: End date description: If this date is provided, it indicates the end of a time range. required: - currency - unit_amount - type PlanMini: type: object title: Plan mini details description: Just the important parts. properties: id: type: string title: Plan ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Plan code description: Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports. pattern: "/^[a-z0-9_+-]+$/i" maxLength: 50 name: type: string title: Name description: This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice. maxLength: 255 Plan: type: object description: Full plan details. properties: id: type: string title: Plan ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Plan code description: Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports. pattern: "/^[a-z0-9_+-]+$/i" maxLength: 50 state: title: State description: The current state of the plan. readOnly: true "$ref": "#/components/schemas/ActiveStateEnum" name: type: string title: Name description: This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice. maxLength: 255 description: type: string title: Description description: Optional description, not displayed. interval_unit: title: Interval unit description: Unit for the plan's billing interval. default: months "$ref": "#/components/schemas/IntervalUnitEnum" interval_length: type: integer title: Interval length description: Length of the plan's billing interval in `interval_unit`. default: 1 minimum: 1 trial_unit: title: Trial unit description: Units for the plan's trial period. default: months "$ref": "#/components/schemas/IntervalUnitEnum" trial_length: type: integer title: Trial length description: Length of plan's trial period in `trial_units`. `0` means `no trial`. default: 0 minimum: 0 trial_requires_billing_info: type: boolean title: Trial Requires BillingInfo 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. default: true total_billing_cycles: type: integer title: Total billing cycles description: Automatically terminate subscriptions after a defined number of billing cycles. Number of billing cycles before the plan automatically stops renewing, defaults to `null` for continuous, automatic renewal. minimum: 0 auto_renew: type: boolean title: Auto renew default: true description: Subscriptions will automatically inherit this value once they are active. If `auto_renew` is `true`, then a subscription will automatically renew its term at renewal. If `auto_renew` is `false`, then a subscription will expire at the end of its term. `auto_renew` can be overridden on the subscription record itself. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" setup_fee_revenue_schedule_type: title: Setup fee revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" accounting_code: type: string title: Plan accounting code description: Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan's code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 setup_fee_accounting_code: type: string title: Setup fee accounting code description: Accounting code for invoice line items for the plan's setup fee. If no value is provided, it defaults to plan's accounting code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the plan, `false` applies tax on the plan." currencies: type: array title: Pricing items: "$ref": "#/components/schemas/PlanPricing" minItems: 1 hosted_pages: type: object title: Hosted pages settings "$ref": "#/components/schemas/PlanHostedPages" allow_any_item_on_subscriptions: type: boolean title: Allow any item on subscriptions 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. 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 plan. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used. 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 readOnly: true required: - code - name PlanCreate: type: object properties: code: type: string title: Plan code description: Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports. pattern: "/^[a-z0-9_+-]+$/i" maxLength: 50 name: type: string title: Name description: This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice. maxLength: 255 description: type: string title: Description description: Optional description, not displayed. accounting_code: type: string title: Plan accounting code description: Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan's code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 interval_unit: title: Interval unit description: Unit for the plan's billing interval. default: months "$ref": "#/components/schemas/IntervalUnitEnum" interval_length: type: integer title: Interval length description: Length of the plan's billing interval in `interval_unit`. default: 1 minimum: 1 trial_unit: title: Trial unit description: Units for the plan's trial period. default: months "$ref": "#/components/schemas/IntervalUnitEnum" trial_length: type: integer title: Trial length description: Length of plan's trial period in `trial_units`. `0` means `no trial`. default: 0 minimum: 0 trial_requires_billing_info: type: boolean title: Trial Requires BillingInfo 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. default: true total_billing_cycles: type: integer title: Total billing cycles description: Automatically terminate plans after a defined number of billing cycles. minimum: 0 auto_renew: type: boolean title: Auto renew default: true description: Subscriptions will automatically inherit this value once they are active. If `auto_renew` is `true`, then a subscription will automatically renew its term at renewal. If `auto_renew` is `false`, then a subscription will expire at the end of its term. `auto_renew` can be overridden on the subscription record itself. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" setup_fee_revenue_schedule_type: title: Setup fee revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" setup_fee_accounting_code: type: string title: Setup fee accounting code description: Accounting code for invoice line items for the plan's setup fee. If no value is provided, it defaults to plan's accounting code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the plan, `false` applies tax on the plan." currencies: type: array title: Pricing items: "$ref": "#/components/schemas/PlanPricing" minItems: 1 hosted_pages: type: object title: Hosted pages settings "$ref": "#/components/schemas/PlanHostedPages" add_ons: type: array title: Add Ons items: "$ref": "#/components/schemas/AddOnCreate" allow_any_item_on_subscriptions: type: boolean title: Allow any item on subscriptions 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. 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 plan. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used. required: - code - name - currencies PlanHostedPages: type: object properties: success_url: type: string title: Success redirect URL description: URL to redirect to after signup on the hosted payment pages. cancel_url: type: string title: Cancel redirect URL (deprecated) description: URL to redirect to on canceled signup on the hosted payment pages. bypass_confirmation: type: boolean title: Bypass confirmation page? description: If `true`, the customer will be sent directly to your `success_url` after a successful signup, bypassing Recurly's hosted confirmation page. display_quantity: type: boolean title: Display quantity? description: Determines if the quantity field is displayed on the hosted pages for the plan. PlanPricing: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 setup_fee: type: number format: float title: Setup fee description: Amount of one-time setup fee automatically charged at the beginning of a subscription billing cycle. For subscription plans with a trial, the setup fee will be charged at the time of signup. Setup fees do not increase with the quantity of a subscription plan. minimum: 0 maximum: 1000000 unit_amount: type: number format: float title: Unit price minimum: 0 maximum: 1000000 PlanUpdate: type: object properties: id: type: string title: Plan ID maxLength: 13 readOnly: true code: type: string title: Plan code description: Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports. pattern: "/^[a-z0-9_+-]+$/i" maxLength: 50 name: type: string title: Name description: This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice. maxLength: 255 description: type: string title: Description description: Optional description, not displayed. accounting_code: type: string title: Plan accounting code description: Accounting code for invoice line items for the plan. If no value is provided, it defaults to plan's code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 trial_unit: title: Trial unit description: Units for the plan's trial period. default: months "$ref": "#/components/schemas/IntervalUnitEnum" trial_length: type: integer title: Trial length description: Length of plan's trial period in `trial_units`. `0` means `no trial`. default: 0 minimum: 0 trial_requires_billing_info: type: boolean title: Trial Requires BillingInfo 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. default: true total_billing_cycles: type: integer title: Total billing cycles description: Automatically terminate plans after a defined number of billing cycles. minimum: 0 auto_renew: type: boolean title: Auto renew default: true description: Subscriptions will automatically inherit this value once they are active. If `auto_renew` is `true`, then a subscription will automatically renew its term at renewal. If `auto_renew` is `false`, then a subscription will expire at the end of its term. `auto_renew` can be overridden on the subscription record itself. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" setup_fee_revenue_schedule_type: title: Setup fee revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" setup_fee_accounting_code: type: string title: Setup fee accounting code description: Accounting code for invoice line items for the plan's setup fee. If no value is provided, it defaults to plan's accounting code. pattern: "/^[a-z0-9_+-]+$/" maxLength: 20 avalara_transaction_type: type: integer title: Avalara Transaction Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 avalara_service_type: type: integer title: Avalara Service Type description: Used by Avalara for Communications taxes. The transaction type in combination with the service type describe how the plan is taxed. Refer to [the documentation](https://help.avalara.com/AvaTax_for_Communications/Tax_Calculation/AvaTax_for_Communications_Tax_Engine/Mapping_Resources/TM_00115_AFC_Modules_Corresponding_Transaction_Types) for more available t/s types. minimum: 0 tax_code: type: string title: Tax code description: Optional field used by Avalara, Vertex, and Recurly's EU VAT tax feature to determine taxation rules. If you have your own AvaTax or Vertex account configured, use their tax codes to assign specific tax rules. If you are using Recurly's EU VAT feature, you can use values of `unknown`, `physical`, or `digital`. maxLength: 50 tax_exempt: type: boolean title: Tax exempt? description: "`true` exempts tax on the plan, `false` applies tax on the plan." currencies: type: array title: Pricing items: "$ref": "#/components/schemas/PlanPricing" minItems: 1 hosted_pages: type: object title: Hosted pages settings "$ref": "#/components/schemas/PlanHostedPages" allow_any_item_on_subscriptions: type: boolean title: Allow any item on subscriptions 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. 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 plan. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used. AddOnPricing: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 unit_amount: type: number format: float title: Unit price minimum: 0 maximum: 1000000 description: Allows up to 2 decimal places. Required unless `unit_amount_decimal` is provided. unit_amount_decimal: type: string title: Unit Amount Decimal minimum: 0 maximum: 1000000 description: | Allows up to 9 decimal places. Only supported when `add_on_type` = `usage`. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. required: - currency TierPricing: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 unit_amount: type: number format: float title: Unit price minimum: 0 maximum: 1000000 description: Allows up to 2 decimal places. Required unless `unit_amount_decimal` is provided. unit_amount_decimal: type: string title: Unit Amount Decimal minimum: 0 maximum: 1000000 description: | Allows up to 9 decimal places. Only supported when `add_on_type` = `usage`. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. required: - currency Pricing: type: object properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 unit_amount: type: number format: float title: Unit price minimum: 0 maximum: 1000000 required: - currency - unit_amount Tier: type: object properties: ending_quantity: type: integer title: Ending quantity description: Ending quantity for the tier. This represents a unit amount for unit-priced add ons, but for percentage type usage add ons, represents the site default currency in its minimum divisible unit. minimum: 1 maximum: 999999999 default: 999999999 usage_percentage: type: string title: Usage Percentage description: Decimal usage percentage. currencies: type: array title: Tier pricing items: "$ref": "#/components/schemas/TierPricing" minItems: 1 Settings: type: object properties: billing_address_requirement: description: | - full: Full Address (Street, City, State, Postal Code and Country) - streetzip: Street and Postal Code only - zip: Postal Code only - none: No Address readOnly: true "$ref": "#/components/schemas/AddressRequirementEnum" accepted_currencies: type: array items: type: string description: 3-letter ISO 4217 currency code. readOnly: true default_currency: type: string description: The default 3-letter ISO 4217 currency code. readOnly: true ShippingAddress: type: object properties: id: type: string title: Shipping Address ID maxLength: 13 readOnly: true object: type: string title: Object type readOnly: true account_id: type: string title: Account ID maxLength: 13 readOnly: true nickname: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 255 email: type: string maxLength: 255 vat_number: type: string maxLength: 20 phone: type: string maxLength: 30 street1: type: string maxLength: 255 street2: type: string maxLength: 255 city: type: string maxLength: 255 region: type: string maxLength: 255 description: State or province. postal_code: type: string maxLength: 20 description: Zip or postal code. country: type: string maxLength: 50 description: Country, 2-letter ISO 3166-1 alpha-2 code. created_at: type: string title: Created at format: date-time readOnly: true updated_at: type: string title: Updated at format: date-time readOnly: true ShippingAddressCreate: type: object properties: nickname: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 255 email: type: string maxLength: 255 vat_number: type: string maxLength: 20 phone: type: string maxLength: 30 street1: type: string maxLength: 255 street2: type: string maxLength: 255 city: type: string maxLength: 255 region: type: string maxLength: 255 description: State or province. postal_code: type: string maxLength: 20 description: Zip or postal code. country: type: string maxLength: 50 description: Country, 2-letter ISO 3166-1 alpha-2 code. required: - first_name - last_name - street1 - city - postal_code - country ShippingAddressList: 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/ShippingAddress" ShippingMethod: type: object properties: id: type: string title: Shipping Method ID readOnly: true maxLength: 13 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 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 readOnly: true ShippingMethodMini: type: object properties: id: type: string title: Shipping Method ID readOnly: true maxLength: 13 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 ShippingMethodCreate: type: object properties: code: type: string title: Code description: The internal name used identify the shipping method. pattern: "/^[a-z0-9_+-]+$/i" 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 required: - code - name ShippingMethodUpdate: type: object properties: code: type: string title: Code description: The internal name used identify the shipping method. pattern: "/^[a-z0-9_+-]+$/i" 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 ShippingFeeCreate: type: object properties: method_id: type: string title: Method ID description: The id of the shipping method used to deliver the purchase. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 13 method_code: type: string title: Method Code description: The code of the shipping method used to deliver the purchase. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 50 amount: type: number format: float title: Amount description: This is priced in the purchase's currency. minimum: 0 ShippingAddressUpdate: type: object properties: id: type: string title: Shipping Address ID maxLength: 13 readOnly: true nickname: type: string maxLength: 255 first_name: type: string maxLength: 255 last_name: type: string maxLength: 255 company: type: string maxLength: 255 email: type: string maxLength: 255 vat_number: type: string maxLength: 20 phone: type: string maxLength: 30 street1: type: string maxLength: 255 street2: type: string maxLength: 255 city: type: string maxLength: 255 region: type: string maxLength: 255 description: State or province. postal_code: type: string maxLength: 20 description: Zip or postal code. country: type: string maxLength: 50 description: Country, 2-letter ISO 3166-1 alpha-2 code. Site: type: object properties: id: type: string title: Site ID readOnly: true maxLength: 13 object: type: string title: Object type readOnly: true subdomain: type: string readOnly: true maxLength: 100 public_api_key: type: string title: Public API Key readOnly: true maxLength: 50 description: This value is used to configure RecurlyJS to submit tokenized billing information. mode: title: Mode maxLength: 15 readOnly: true "$ref": "#/components/schemas/SiteModeEnum" address: "$ref": "#/components/schemas/Address" settings: "$ref": "#/components/schemas/Settings" features: type: array title: Features description: A list of features enabled for the site. items: readOnly: true "$ref": "#/components/schemas/FeaturesEnum" created_at: type: string format: date-time title: Created at readOnly: true updated_at: type: string format: date-time title: Updated at readOnly: true deleted_at: type: string format: date-time title: Deleted at readOnly: true Subscription: type: object properties: id: type: string title: Subscription ID maxLength: 13 object: type: string title: Object type 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 account: "$ref": "#/components/schemas/AccountMini" plan: "$ref": "#/components/schemas/PlanMini" state: title: State "$ref": "#/components/schemas/SubscriptionStateEnum" shipping: "$ref": "#/components/schemas/SubscriptionShipping" coupon_redemptions: type: array title: Coupon redemptions description: Returns subscription level coupon redemptions that are tied to this subscription. items: "$ref": "#/components/schemas/CouponRedemptionMini" pending_change: "$ref": "#/components/schemas/SubscriptionChange" current_period_started_at: type: string format: date-time title: Current billing period started at current_period_ends_at: type: string format: date-time title: Current billing period ends at current_term_started_at: type: string format: date-time title: Current term started at description: The start date of the term when the first billing period starts. The subscription term is the length of time that a customer will be committed to a subscription. A term can span multiple billing periods. current_term_ends_at: type: string format: date-time title: Current term ends at description: When the term ends. This is calculated by a plan's interval and `total_billing_cycles` in a term. Subscription changes with a `timeframe=renewal` will be applied on this date. trial_started_at: type: string format: date-time title: Trial period started at trial_ends_at: type: string format: date-time title: Trial period ends at remaining_billing_cycles: type: integer title: Remaining billing cycles description: The remaining billing cycles in the current term. total_billing_cycles: type: integer title: Total billing cycles description: The number of cycles/billing periods in a term. When `remaining_billing_cycles=0`, if `auto_renew=true` the subscription will renew and a new term will begin, otherwise the subscription will expire. renewal_billing_cycles: type: integer title: Renewal billing cycles description: If `auto_renew=true`, when a term completes, `total_billing_cycles` takes this value as the length of subsequent terms. Defaults to the plan's `total_billing_cycles`. auto_renew: type: boolean default: true title: Auto renew description: Whether the subscription renews at the end of its term. paused_at: type: string format: date-time title: Paused at description: Null unless subscription is paused or will pause at the end of the current billing period. remaining_pause_cycles: type: integer title: Remaining pause cycles description: Null unless subscription is paused or will pause at the end of the current billing period. currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" unit_amount: type: number format: float title: Subscription unit price quantity: type: integer title: Subscription quantity minimum: 0 add_ons: type: array title: Add-ons items: "$ref": "#/components/schemas/SubscriptionAddOn" add_ons_total: type: number format: float title: Total price of add-ons minimum: 0 subtotal: type: number format: float title: Estimated total, before tax. minimum: 0 tax: type: number format: float title: Estimated tax tax_info: "$ref": "#/components/schemas/TaxInfo" total: type: number format: float title: Estimated total collection_method: title: Collection method default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 terms_and_conditions: type: string title: Terms and conditions customer_notes: type: string title: Customer notes expiration_reason: type: string title: Expiration reason custom_fields: "$ref": "#/components/schemas/CustomFields" created_at: type: string format: date-time title: Created at updated_at: type: string format: date-time title: Last updated at activated_at: type: string format: date-time title: Activated at canceled_at: type: string format: date-time title: Canceled at expires_at: type: string format: date-time title: Expires at bank_account_authorized_at: type: string format: date-time title: Bank account authorized description: Recurring subscriptions paid with ACH will have this attribute set. 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. gateway_code: type: string title: Gateway Code description: If present, this subscription's transactions will use the payment gateway with this code. maxLength: 13 billing_info_id: type: string title: Billing Info ID description: Billing Info ID. SubscriptionAddOn: type: object title: Subscription Add-on description: This links an Add-on to a specific Subscription. properties: id: type: string title: Subscription Add-on ID maxLength: 13 object: type: string title: Object type subscription_id: type: string title: Subscription ID maxLength: 13 add_on: "$ref": "#/components/schemas/AddOnMini" add_on_source: "$ref": "#/components/schemas/AddOnSourceEnum" quantity: type: integer title: Add-on quantity minimum: 0 unit_amount: type: number format: float title: Add-on unit price description: Supports up to 2 decimal places. unit_amount_decimal: type: string format: decimal title: Add-on unit in decimal price description: Supports up to 9 decimal places. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" tier_type: "$ref": "#/components/schemas/TierTypeEnum" tiers: type: array title: Tiers items: "$ref": "#/components/schemas/SubscriptionAddOnTier" minItems: 1 description: | If tiers are provided in the request, all existing tiers on the Subscription Add-on will be removed and replaced by the tiers in the request. usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage. created_at: type: string format: date-time title: Created at updated_at: type: string format: date-time title: Updated at expired_at: type: string format: date-time title: Expired at SubscriptionAddOnCreate: type: object properties: code: type: string title: Add-on code maxLength: 50 description: | If `add_on_source` is set to `plan_add_on` or left blank, then plan's add-on `code` should be used. If `add_on_source` is set to `item`, then the `code` from the associated item should be used. add_on_source: "$ref": "#/components/schemas/AddOnSourceEnum" quantity: type: integer title: Quantity minimum: 0 default: 1 unit_amount: type: number format: float title: Unit amount description: | Allows up to 2 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` cannot be provided. minimum: 0 maximum: 1000000 unit_amount_decimal: type: string format: decimal title: Unit Amount Decimal description: | Allows up to 9 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount_decimal` cannot be provided. Only supported when the plan add-on's `add_on_type` = `usage`. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. minimum: 0 maximum: 1000000 tiers: type: array title: Tiers items: "$ref": "#/components/schemas/SubscriptionAddOnTier" minItems: 1 description: | If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided. See our [Guide](https://developers.recurly.com/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models. usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if `add_on_type` is usage and `usage_type` is percentage. Must be omitted otherwise. `usage_percentage` does not support tiers. See our [Guide](https://developers.recurly.com/guides/usage-based-billing-guide.html) for an overview of how to configure usage add-ons. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" required: - code SubscriptionAddOnUpdate: type: object properties: id: type: string title: Subscription Add-on ID. description: | When an id is provided, the existing subscription add-on attributes will persist unless overridden in the request. maxLength: 13 code: type: string title: Add-on code maxLength: 50 description: | If a code is provided without an id, the subscription add-on attributes will be set to the current value for those attributes on the plan add-on unless provided in the request. If `add_on_source` is set to `plan_add_on` or left blank, then plan's add-on `code` should be used. If `add_on_source` is set to `item`, then the `code` from the associated item should be used. add_on_source: "$ref": "#/components/schemas/AddOnSourceEnum" quantity: type: integer title: Quantity minimum: 0 unit_amount: type: number format: float title: Unit amount description: | Allows up to 2 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount` cannot be provided. minimum: 0 maximum: 1000000 unit_amount_decimal: type: string title: Unit amount decimal description: | Allows up to 9 decimal places. Optionally, override the add-on's default unit amount. If the plan add-on's `tier_type` is `tiered`, `volume`, or `stairstep`, then `unit_amount_decimal` cannot be provided. Only supported when the plan add-on's `add_on_type` = `usage`. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. tiers: type: array title: Tiers items: "$ref": "#/components/schemas/SubscriptionAddOnTier" minItems: 1 description: | If the plan add-on's `tier_type` is `flat`, then `tiers` must be absent. The `tiers` object must include one to many tiers with `ending_quantity` and `unit_amount`. There must be one tier with an `ending_quantity` of 999999999 which is the default if not provided. usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" SubscriptionAddOnTier: type: object properties: ending_quantity: type: integer title: Ending quantity minimum: 1 maximum: 999999999 default: 999999999 unit_amount: type: number format: float title: Unit amount minimum: 0 maximum: 1000000 description: Allows up to 2 decimal places. Optionally, override the tiers' default unit amount. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided. unit_amount_decimal: type: string title: Unit amount decimal description: | Allows up to 9 decimal places. Optionally, override tiers' default unit amount. If `unit_amount_decimal` is provided, `unit_amount` cannot be provided. If add-on's `add_on_type` is `usage` and `usage_type` is `percentage`, cannot be provided. usage_percentage: type: string title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places represented as a string. A value between 0.0 and 100.0. Optionally, override tiers' default usage percentage. Required if add-on's `add_on_type` is `usage` and `usage_type` is `percentage`. Must be omitted otherwise. SubscriptionCancel: type: object properties: timeframe: title: Timeframe description: The timeframe parameter controls when the expiration takes place. The `bill_date` timeframe causes the subscription to expire when the subscription is scheduled to bill next. The `term_end` timeframe causes the subscription to continue to bill until the end of the subscription term, then expire. default: term_end "$ref": "#/components/schemas/TimeframeEnum" SubscriptionChange: type: object title: Subscription Change properties: id: type: string title: Subscription Change ID description: The ID of the Subscription Change. object: type: string title: Object type subscription_id: type: string title: Subscription ID description: The ID of the subscription that is going to be changed. maxLength: 13 plan: "$ref": "#/components/schemas/PlanMini" add_ons: type: array title: Add-ons description: These add-ons will be used when the subscription renews. items: "$ref": "#/components/schemas/SubscriptionAddOn" unit_amount: type: number format: float title: Unit amount quantity: type: integer title: Subscription quantity shipping: "$ref": "#/components/schemas/SubscriptionShipping" activate_at: type: string format: date-time title: Activated at readOnly: true activated: type: boolean title: Activated? description: Returns `true` if the subscription change is activated. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" invoice_collection: title: Invoice Collection "$ref": "#/components/schemas/InvoiceCollection" custom_fields: "$ref": "#/components/schemas/CustomFields" created_at: type: string format: date-time title: Created at readOnly: true updated_at: type: string format: date-time title: Updated at readOnly: true deleted_at: type: string format: date-time title: Deleted at readOnly: true billing_info: "$ref": "#/components/schemas/SubscriptionChangeBillingInfo" SubscriptionChangeBillingInfo: type: object description: Accept nested attributes for three_d_secure_action_result_token_id properties: three_d_secure_action_result_token_id: type: string title: 3-D Secure action result token ID description: A token generated by Recurly.js after completing a 3-D Secure device fingerprinting or authentication challenge. maxLength: 22 SubscriptionChangeBillingInfoCreate: allOf: - "$ref": "#/components/schemas/SubscriptionChangeBillingInfo" SubscriptionChangeCreate: type: object properties: timeframe: title: Timeframe description: The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now, when the subscription is next billed, or when the subscription term ends. Generally, if you're performing an upgrade, you will want the change to occur immediately (now). If you're performing a downgrade, you should set the timeframe to `term_end` or `bill_date` so the change takes effect at a scheduled billing date. The `renewal` timeframe option is accepted as an alias for `term_end`. default: now "$ref": "#/components/schemas/ChangeTimeframeEnum" plan_id: type: string title: Plan ID maxLength: 13 description: If you want to change to a new plan, you can provide the plan's code or id. If both are provided the `plan_id` will be used. plan_code: type: string title: New plan code maxLength: 50 description: If you want to change to a new plan, you can provide the plan's code or id. If both are provided the `plan_id` will be used. unit_amount: type: number format: float title: Custom subscription price description: Optionally, sets custom pricing for the subscription, overriding the plan's default unit amount. The subscription's current currency will be used. minimum: 0 maximum: 1000000 quantity: type: integer title: Quantity description: Optionally override the default quantity of 1. default: 1 minimum: 0 shipping: "$ref": "#/components/schemas/SubscriptionChangeShippingCreate" coupon_codes: type: array title: Coupon codes description: A list of coupon_codes to be redeemed on the subscription during the change. Only allowed if timeframe is now and you change something about the subscription that creates an invoice. items: type: string add_ons: type: array title: Add-ons description: | If you provide a value for this field it will replace any existing add-ons. So, when adding or modifying an add-on, you need to include the existing subscription add-ons. Unchanged add-ons can be included just using the subscription add-on''s ID: `{"id": "abc123"}`. If this value is omitted your existing add-ons will be unaffected. To remove all existing add-ons, this value should be an empty array.' If a subscription add-on's `code` is supplied without the `id`, `{"code": "def456"}`, the subscription add-on attributes will be set to the current values of the plan add-on unless provided in the request. - If an `id` is passed, any attributes not passed in will pull from the existing subscription add-on - If a `code` is passed, any attributes not passed in will pull from the current values of the plan add-on - Attributes passed in as part of the request will override either of the above scenarios items: "$ref": "#/components/schemas/SubscriptionAddOnUpdate" collection_method: title: Collection method default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" custom_fields: "$ref": "#/components/schemas/CustomFields" po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" billing_info: "$ref": "#/components/schemas/SubscriptionChangeBillingInfoCreate" SubscriptionChangeShippingCreate: type: object title: Shipping details that will be changed on a subscription description: Shipping addresses are tied to a customer's account. Each account can have up to 20 different shipping addresses, and if you have enabled multiple subscriptions per account, you can associate different shipping addresses to each subscription. properties: method_id: type: string title: Method ID description: The id of the shipping method used to deliver the subscription. To remove shipping set this to `null` and the `amount=0`. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 13 method_code: type: string title: Method Code description: The code of the shipping method used to deliver the subscription. To remove shipping set this to `null` and the `amount=0`. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 50 amount: type: number format: float title: Assigns the subscription's shipping cost. If this is greater than zero then a `method_id` or `method_code` is required. address_id: type: string titpe: Shipping address ID description: Assign a shipping address from the account's existing shipping addresses. If this and address are both present, address will take precedence. address: "$ref": "#/components/schemas/ShippingAddressCreate" SubscriptionCreate: type: object properties: plan_code: type: string title: Plan code maxLength: 50 description: You must provide either a `plan_code` or `plan_id`. If both are provided the `plan_id` will be used. plan_id: type: string title: Plan ID maxLength: 13 description: You must provide either a `plan_code` or `plan_id`. If both are provided the `plan_id` will be used. account: "$ref": "#/components/schemas/AccountCreate" billing_info_id: type: string title: Billing Info ID description: The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. shipping: title: Shipping address description: Create a shipping address on the account and assign it to the subscription. "$ref": "#/components/schemas/SubscriptionShippingCreate" collection_method: title: Collection method default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 unit_amount: type: number format: float title: Custom subscription pricing description: Override the unit amount of the subscription plan by setting this value. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. minimum: 0 maximum: 1000000 quantity: type: integer title: Quantity description: Optionally override the default quantity of 1. default: 1 minimum: 0 add_ons: type: array title: Add-ons items: "$ref": "#/components/schemas/SubscriptionAddOnCreate" coupon_codes: type: array title: Coupon codes description: A list of coupon_codes to be redeemed on the subscription or account during the purchase. items: type: string custom_fields: "$ref": "#/components/schemas/CustomFields" trial_ends_at: type: string format: date-time title: Trial ends at description: If set, overrides the default trial behavior for the subscription. When the current date time or a past date time is provided the subscription will begin with no trial phase (overriding any plan default trial). When a future date time is provided the subscription will begin with a trial phase ending at the specified date time. starts_at: type: string format: date-time title: Start date description: If set, the subscription will begin in the future on this date. The subscription will apply the setup fee and trial period, unless the plan has no trial. next_bill_date: type: string format: date-time title: Next bill date description: If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). This can be used to align the subscription’s billing to a specific day of the month. The initial invoice will be prorated for the period between the subscription's activation date and the billing period end date. Subsequent periods will be based off the plan interval. For a subscription with a trial period, this will change when the trial expires. total_billing_cycles: type: integer title: Total billing cycles description: The number of cycles/billing periods in a term. When `remaining_billing_cycles=0`, if `auto_renew=true` the subscription will renew and a new term will begin, otherwise the subscription will expire. minimum: 1 renewal_billing_cycles: type: integer title: Renewal billing cycles description: If `auto_renew=true`, when a term completes, `total_billing_cycles` takes this value as the length of subsequent terms. Defaults to the plan's `total_billing_cycles`. auto_renew: type: boolean default: true title: Auto renew description: Whether the subscription renews at the end of its term. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" terms_and_conditions: type: string title: Terms and conditions description: This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals. customer_notes: type: string title: Customer notes description: This will default to the Customer Notes text specified on the Invoice Settings. Specify custom notes to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. credit_customer_notes: type: string title: Credit customer notes description: If there are pending credits on the account that will be invoiced during the subscription creation, these will be used as the Customer Notes on the credit invoice. po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" required: - plan_code - currency - account SubscriptionPurchase: type: object properties: plan_code: type: string title: Plan code plan_id: type: string title: Plan ID maxLength: 13 unit_amount: type: number format: float title: Custom subscription pricing description: Override the unit amount of the subscription plan by setting this value. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. minimum: 0 maximum: 1000000 quantity: type: integer title: Quantity description: Optionally override the default quantity of 1. default: 1 minimum: 0 add_ons: type: array title: Add-ons items: "$ref": "#/components/schemas/SubscriptionAddOnCreate" custom_fields: "$ref": "#/components/schemas/CustomFields" shipping: title: Shipping address description: Create a shipping address on the account and assign it to the subscription. "$ref": "#/components/schemas/SubscriptionShippingPurchase" trial_ends_at: type: string format: date-time title: Trial ends at description: If set, overrides the default trial behavior for the subscription. When the current date time or a past date time is provided the subscription will begin with no trial phase (overriding any plan default trial). When a future date time is provided the subscription will begin with a trial phase ending at the specified date time. starts_at: type: string format: date-time title: Start date description: If set, the subscription will begin in the future on this date. The subscription will apply the setup fee and trial period, unless the plan has no trial. next_bill_date: type: string format: date-time title: Next bill date description: If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). This can be used to align the subscription’s billing to a specific day of the month. The initial invoice will be prorated for the period between the subscription's activation date and the billing period end date. Subsequent periods will be based off the plan interval. For a subscription with a trial period, this will change when the trial expires. total_billing_cycles: type: integer title: Total billing cycles description: The number of cycles/billing periods in a term. When `remaining_billing_cycles=0`, if `auto_renew=true` the subscription will renew and a new term will begin, otherwise the subscription will expire. minimum: 1 renewal_billing_cycles: type: integer title: Renewal billing cycles description: If `auto_renew=true`, when a term completes, `total_billing_cycles` takes this value as the length of subsequent terms. Defaults to the plan's `total_billing_cycles`. auto_renew: type: boolean default: true title: Auto renew description: Whether the subscription renews at the end of its term. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" required: - plan_code SubscriptionUpdate: type: object properties: collection_method: title: Change collection method "$ref": "#/components/schemas/CollectionMethodEnum" custom_fields: "$ref": "#/components/schemas/CustomFields" remaining_billing_cycles: type: integer title: Remaining billing cycles description: The remaining billing cycles in the current term. renewal_billing_cycles: type: integer title: Renewal billing cycles description: If `auto_renew=true`, when a term completes, `total_billing_cycles` takes this value as the length of subsequent terms. Defaults to the plan's `total_billing_cycles`. auto_renew: type: boolean default: true title: Auto renew description: Whether the subscription renews at the end of its term. next_bill_date: type: string format: date-time title: Next bill date description: If present, this sets the date the subscription's next billing period will start (`current_period_ends_at`). This can be used to align the subscription’s billing to a specific day of the month. For a subscription in a trial period, this will change when the trial expires. This parameter is useful for postponement of a subscription to change its billing date without proration. revenue_schedule_type: title: Revenue schedule type "$ref": "#/components/schemas/RevenueScheduleTypeEnum" terms_and_conditions: type: string title: Terms and conditions description: Specify custom notes to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals. customer_notes: type: string title: Customer notes description: Specify custom notes to add or override Customer Notes. Custom notes will stay with a subscription on all renewals. po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Terms that the subscription is due on description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 gateway_code: type: string title: Gateway Code description: If present, this subscription's transactions will use the payment gateway with this code. maxLength: 13 shipping: "$ref": "#/components/schemas/SubscriptionShippingUpdate" billing_info_id: type: string title: Billing Info ID description: The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. SubscriptionPause: type: object properties: remaining_pause_cycles: type: integer title: Remaining pause cycles description: Number of billing cycles to pause the subscriptions. A value of 0 will cancel any pending pauses on the subscription. required: - remaining_pause_cycles SubscriptionShipping: type: object title: Subscription shipping details properties: object: type: string title: Object type address: "$ref": "#/components/schemas/ShippingAddress" method: "$ref": "#/components/schemas/ShippingMethodMini" amount: type: number format: float title: Subscription's shipping cost SubscriptionShippingCreate: type: object title: Subscription shipping details properties: address: "$ref": "#/components/schemas/ShippingAddressCreate" address_id: type: string title: Shipping address ID description: Assign a shipping address from the account's existing shipping addresses. If `address_id` and `address` are both present, `address` will be used. maxLength: 13 method_id: type: string title: Service ID description: The id of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 13 method_code: type: string title: Service Code description: The code of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 50 amount: type: number format: float title: Assigns the subscription's shipping cost. If this is greater than zero then a `method_id` or `method_code` is required. SubscriptionShippingUpdate: type: object title: Subscription shipping details properties: object: type: string title: Object type address: "$ref": "#/components/schemas/ShippingAddressCreate" address_id: type: string title: Shipping Address ID description: Assign a shipping address from the account's existing shipping addresses. maxLength: 13 SubscriptionShippingPurchase: type: object title: Subscription shipping details properties: method_id: type: string title: Service ID description: The id of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 13 method_code: type: string title: Service Code description: The code of the shipping method used to deliver the subscription. If `method_id` and `method_code` are both present, `method_id` will be used. maxLength: 50 amount: type: number format: float title: Assigns the subscription's shipping cost. If this is greater than zero then a `method_id` or `method_code` is required. TaxInfo: type: object title: Tax info properties: type: type: string title: Type 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. region: type: string title: Region 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. rate: type: number format: float title: Rate tax_details: type: array description: Provides additional tax details for Canadian Sales Tax when there is tax applied at both the country and province levels. This will only be populated for the Invoice response when fetching a single invoice and not for the InvoiceList or LineItem. items: "$ref": "#/components/schemas/TaxDetail" TaxDetail: type: object title: Tax detail properties: type: type: string title: Type description: Provides the tax type for the region. For Canadian Sales Tax, this will be GST, HST, QST or PST. region: type: string title: Region description: Provides the tax region applied on an invoice. For Canadian Sales Tax, this will be either the 2 letter province code or country code. rate: type: number format: float title: Rate description: Provides the tax rate for the region. tax: type: number format: float title: Tax description: The total tax applied for this tax type. Transaction: type: object properties: id: type: string title: Transaction ID maxLength: 13 object: type: string title: Object type uuid: type: string title: Recurly UUID description: The UUID is useful for matching data with the CSV exports and building URLs into Recurly's UI. maxLength: 32 original_transaction_id: type: string title: Original Transaction ID description: If this transaction is a refund (`type=refund`), this will be the ID of the original transaction on the invoice being refunded. maxLength: 13 account: "$ref": "#/components/schemas/AccountMini" invoice: "$ref": "#/components/schemas/InvoiceMini" voided_by_invoice: "$ref": "#/components/schemas/InvoiceMini" subscription_ids: type: array title: Subscription IDs description: If the transaction is charging or refunding for one or more subscriptions, these are their IDs. items: type: string title: Subscription ID maxLength: 13 type: title: Transaction type description: | - `authorization` – verifies billing information and places a hold on money in the customer's account. - `capture` – captures funds held by an authorization and completes a purchase. - `purchase` – combines the authorization and capture in one transaction. - `refund` – returns all or a portion of the money collected in a previous transaction to the customer. - `verify` – a $0 or $1 transaction used to verify billing information which is immediately voided. "$ref": "#/components/schemas/TransactionTypeEnum" origin: title: Origin of transaction description: Describes how the transaction was triggered. "$ref": "#/components/schemas/TransactionOriginEnum" currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 amount: type: number format: float title: Amount description: Total transaction amount sent to the payment gateway. status: title: Transaction status description: The current transaction status. Note that the status may change, e.g. a `pending` transaction may become `declined` or `success` may later become `void`. "$ref": "#/components/schemas/TransactionStatusEnum" success: type: boolean title: Success? description: Did this transaction complete successfully? backup_payment_method_used: type: boolean title: Backup Payment Method Used? description: Indicates if the transaction was completed using a backup payment refunded: type: boolean title: Refunded? description: Indicates if part or all of this transaction was refunded. billing_address: "$ref": "#/components/schemas/AddressWithName" collection_method: description: The method by which the payment was collected. "$ref": "#/components/schemas/CollectionMethodEnum" payment_method: "$ref": "#/components/schemas/PaymentMethod" ip_address_v4: type: string title: IP address description: | IP address provided when the billing information was collected: - When the customer enters billing information into the Recurly.js or Hosted Payment Pages, Recurly records the IP address. - When the merchant enters billing information using the API, the merchant may provide an IP address. - When the merchant enters billing information using the UI, no IP address is recorded. ip_address_country: type: string title: Origin IP address country, 2-letter ISO 3166-1 alpha-2 code, if known by Recurly. status_code: type: string title: Status code status_message: type: string title: Status message description: For declined (`success=false`) transactions, the message displayed to the merchant. customer_message: type: string title: Customer message description: For declined (`success=false`) transactions, the message displayed to the customer. customer_message_locale: type: string title: Language code for the message payment_gateway: type: object x-class-name: TransactionPaymentGateway properties: id: type: string object: type: string title: Object type type: type: string name: type: string gateway_message: type: string title: Gateway message description: Transaction message from the payment gateway. gateway_reference: type: string title: Gateway reference description: Transaction reference number from the payment gateway. gateway_approval_code: type: string title: Transaction approval code from the payment gateway. gateway_response_code: type: string title: For declined transactions (`success=false`), this field lists the gateway error code. gateway_response_time: type: number format: float title: Gateway response time description: Time, in seconds, for gateway to process the transaction. gateway_response_values: type: object title: Gateway response values description: The values in this field will vary from gateway to gateway. cvv_check: title: CVV check description: When processed, result from checking the CVV/CVC value on the transaction. "$ref": "#/components/schemas/CvvCheckEnum" avs_check: title: AVS check description: When processed, result from checking the overall AVS on the transaction. "$ref": "#/components/schemas/AvsCheckEnum" created_at: type: string format: date-time title: Created at updated_at: type: string format: date-time title: Updated at voided_at: type: string format: date-time title: Voided at collected_at: type: string format: date-time title: Collected at, or if not collected yet, the time the transaction was created. ExternalTransaction: type: object properties: payment_method: type: string title: Payment Method description: Payment method used for external transaction. "$ref": "#/components/schemas/ExternalPaymentMethodEnum" description: type: string title: Description description: Used as the transaction's description. maxLength: 50 amount: type: number format: float title: Amount description: The total amount of the transcaction. Cannot excceed the invoice total. collected_at: type: string format: date-time title: Collected At description: Datetime that the external payment was collected. Defaults to current datetime. UniqueCouponCode: type: object description: A unique coupon code for a bulk coupon. properties: id: type: string title: Unique Coupon Code ID readOnly: true object: type: string title: Object type readOnly: true code: type: string title: Coupon code description: The code the customer enters to redeem the coupon. state: title: State description: Indicates if the unique coupon code is redeemable or why not. "$ref": "#/components/schemas/CouponCodeStateEnum" bulk_coupon_id: type: string title: Bulk Coupon ID description: The Coupon ID of the parent Bulk Coupon readOnly: true bulk_coupon_code: type: string title: Bulk Coupon code description: The Coupon code of the parent Bulk Coupon created_at: type: string title: Created at format: date-time readOnly: true updated_at: type: string title: Updated at format: date-time readOnly: true redeemed_at: type: string title: Redeemed at description: The date and time the unique coupon code was redeemed. format: date-time readOnly: true expired_at: type: string title: Expired at description: The date and time the coupon was expired early or reached its `max_redemptions`. format: date-time UniqueCouponCodeList: 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/UniqueCouponCode" UniqueCouponCodeParams: type: object description: Parameters to be passed to the `list_unique_coupon_codes` endpoint to obtain the newly generated codes. properties: limit: type: integer title: The number of UniqueCouponCodes that will be generated order: type: string title: Sort order to list newly generated UniqueCouponCodes (should always be `asc`) sort: type: string title: Sort field to list newly generated UniqueCouponCodes (should always be `created_at`) begin_time: type: string title: Begin time query parameter description: The date-time to be included when listing UniqueCouponCodes format: date-time Usage: type: object properties: id: type: string object: type: string title: Object type merchant_tag: type: string description: Custom field 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. amount: type: number format: float description: The amount of usage. Can be positive, negative, or 0. No decimals allowed, we will strip them. If the usage-based add-on is billed with a percentage, your usage will be a monetary amount you will want to format in cents. (e.g., $5.00 is "500"). usage_type: "$ref": "#/components/schemas/UsageTypeEnum" tier_type: "$ref": "#/components/schemas/TierTypeEnum" tiers: type: array title: Tiers items: "$ref": "#/components/schemas/SubscriptionAddOnTier" description: The tiers and prices of the subscription based on the usage_timestamp. If tier_type = flat, tiers = null measured_unit_id: type: string description: The ID of the measured unit associated with the add-on the usage record is for. 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. usage_percentage: type: number format: float title: Usage Percentage description: The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. unit_amount: type: number format: float title: Unit price unit_amount_decimal: type: string title: Unit Amount Decimal minimum: 0 maximum: 1000000 description: Unit price that can optionally support a sub-cent value. billed_at: type: string format: date-time description: When the usage record was billed on an invoice. 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 billed on an invoice. UsageCreate: type: object properties: merchant_tag: type: string description: Custom field 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. amount: type: number format: float description: The amount of usage. Can be positive, negative, or 0. No decimals allowed, we will strip them. If the usage-based add-on is billed with a percentage, your usage will be a monetary amount you will want to format in cents. (e.g., $5.00 is "500"). 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. UsageList: 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/Usage" User: type: object properties: id: type: string readOnly: true object: type: string title: Object type readOnly: true email: type: string format: email first_name: type: string last_name: type: string time_zone: type: string created_at: type: string format: date-time readOnly: true deleted_at: type: string format: date-time readOnly: true PurchaseCreate: type: object description: A purchase is only a request data type and is not persistent in Recurly, an InvoiceCollection will be the returned type. properties: currency: type: string title: Currency description: 3-letter ISO 4217 currency code. maxLength: 3 account: "$ref": "#/components/schemas/AccountPurchase" billing_info_id: type: string description: The `billing_info_id` is the value that represents a specific billing info for an end customer. When `billing_info_id` is used to assign billing info to the subscription, all future billing events for the subscription will bill to the specified billing info. collection_method: title: Collection method description: Must be set to manual in order to preview a purchase for an Account that does not have payment information associated with the Billing Info. default: automatic "$ref": "#/components/schemas/CollectionMethodEnum" po_number: type: string title: Purchase order number description: For manual invoicing, this identifies the PO number associated with the subscription. maxLength: 50 net_terms: type: integer title: Net terms description: Integer representing the number of days after an invoice's creation that the invoice will become past due. If an invoice's net terms are set to '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. minimum: 0 default: 0 terms_and_conditions: type: string title: Terms and conditions description: Terms and conditions to be put on the purchase invoice. customer_notes: type: string title: Customer notes vat_reverse_charge_notes: type: string title: VAT reverse charge notes description: VAT reverse charge notes for cross border European tax settlement. credit_customer_notes: type: string title: Credit customer notes description: Notes to be put on the credit invoice resulting from credits in the purchase, if any. gateway_code: type: string title: Gateway Code description: The default payment gateway identifier to be used for the purchase transaction. This will also be applied as the default for any subscriptions included in the purchase request. maxLength: 13 shipping: type: object x-class-name: ShippingPurchase properties: address_id: type: string title: Shipping address ID description: Assign a shipping address from the account's existing shipping addresses. If this and `address` are both present, `address` will take precedence. maxLength: 13 address: "$ref": "#/components/schemas/ShippingAddressCreate" fees: type: array title: Shipping fees description: A list of shipping fees to be created as charges with the purchase. items: "$ref": "#/components/schemas/ShippingFeeCreate" line_items: type: array title: Line items description: A list of one time charges or credits to be created with the purchase. items: "$ref": "#/components/schemas/LineItemCreate" subscriptions: type: array title: Subscriptions description: A list of subscriptions to be created with the purchase. items: "$ref": "#/components/schemas/SubscriptionPurchase" coupon_codes: type: array title: Coupon codes description: A list of coupon_codes to be redeemed on the subscription or account during the purchase. items: type: string gift_card_redemption_code: type: string title: Gift card redemption code description: A gift card redemption code to be redeemed on the purchase invoice. transaction_type: 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. "$ref": "#/components/schemas/GatewayTransactionTypeEnum" required: - currency - account DunningCampaign: type: object description: Settings for a dunning campaign. properties: id: type: string object: type: string title: Object type 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. DunningCampaignList: 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/DunningCampaign" DunningCycle: type: object properties: type: "$ref": "#/components/schemas/DunningCycleTypeEnum" 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. DunningCampaignsBulkUpdate: properties: plan_codes: type: array maxItems: 200 description: List of `plan_codes` associated with the Plans for which the dunning campaign should be updated. Required unless `plan_ids` is present. items: type: string plan_ids: type: array maxItems: 200 description: List of `plan_ids` associated with the Plans for which the dunning campaign should be updated. Required unless `plan_codes` is present. items: type: string DunningCampaignsBulkUpdateResponse: properties: object: type: string title: Object type readOnly: true plans: type: array title: Plans description: An array containing all of the `Plan` resources that have been updated. maxItems: 200 items: "$ref": "#/components/schemas/Plan" PaymentMethod: properties: object: "$ref": "#/components/schemas/PaymentMethodEnum" card_type: description: Visa, MasterCard, American Express, Discover, JCB, etc. "$ref": "#/components/schemas/CardTypeEnum" first_six: type: string description: Credit card number's first six digits. maxLength: 6 last_four: type: string description: Credit card number's last four digits. Will refer to bank account if payment method is ACH. maxLength: 4 last_two: type: string description: The IBAN bank account's last two digits. maxLength: 2 exp_month: type: integer description: Expiration month. maxLength: 2 exp_year: type: integer description: Expiration year. maxLength: 4 gateway_token: type: string description: A token used in place of a credit card in order to perform transactions. maxLength: 50 cc_bin_country: type: string description: The 2-letter ISO 3166-1 alpha-2 country code associated with the credit card BIN, if known by Recurly. Available on the BillingInfo object only. Available when the BIN country lookup feature is enabled. gateway_code: type: string description: An identifier for a specific payment gateway. maxLength: 13 billing_agreement_id: type: string description: Billing Agreement identifier. Only present for Amazon or Paypal payment methods. name_on_account: type: string description: The name associated with the bank account. account_type: description: The bank account type. Only present for ACH payment methods. "$ref": "#/components/schemas/AccountTypeEnum" routing_number: type: string description: The bank account's routing number. Only present for ACH payment methods. routing_number_bank: type: string description: The bank name of this routing number. Error: type: object properties: type: title: Type "$ref": "#/components/schemas/ErrorTypeEnum" message: type: string title: Message params: type: array title: Parameter specific errors items: type: object properties: param: type: string ErrorMayHaveTransaction: allOf: - "$ref": "#/components/schemas/Error" - type: object properties: transaction_error: type: object x-class-name: TransactionError title: Transaction error details description: This is only included on errors with `type=transaction`. properties: object: type: string title: Object type transaction_id: type: string title: Transaction ID maxLength: 13 category: title: Category "$ref": "#/components/schemas/ErrorCategoryEnum" code: title: Code "$ref": "#/components/schemas/ErrorCodeEnum" message: type: string title: Customer message merchant_advice: type: string title: Merchant message three_d_secure_action_token_id: type: string title: 3-D Secure action token id description: Returned when 3-D Secure authentication is required for a transaction. Pass this value to Recurly.js so it can continue the challenge flow. maxLength: 22 RelatedTypeEnum: type: string enum: - account - item - subscription RefundTypeEnum: type: string enum: - full - none - partial AlphanumericSortEnum: type: string enum: - asc - desc UsageSortEnum: type: string default: usage_timestamp enum: - recorded_timestamp - usage_timestamp UsageTypeEnum: type: string enum: - price - percentage title: Usage Type description: Type of usage, returns usage type if `add_on_type` is `usage`. BillingStatusEnum: type: string default: unbilled enum: - unbilled - billed - all TimestampSortEnum: type: string enum: - created_at - updated_at ActiveStateEnum: type: string enum: - active - inactive FilterSubscriptionStateEnum: type: string enum: - active - canceled - expired - future - in_trial - live TrueEnum: type: string enum: - true LineItemStateEnum: type: string enum: - invoiced - pending LineItemTypeEnum: type: string enum: - charge - credit FilterTransactionTypeEnum: type: string enum: - authorization - capture - payment - purchase - refund - verify FilterInvoiceTypeEnum: type: string enum: - charge - credit - legacy - non-legacy ChannelEnum: type: string enum: - advertising - blog - direct_traffic - email - events - marketing_content - organic_search - other - outbound_sales - paid_search - public_relations - referral - social_media PreferredLocaleEnum: type: string enum: - da-DK - de-CH - de-DE - en-AU - en-CA - en-GB - en-IE - en-NZ - en-US - es-ES - es-MX - es-US - fi-FI - fr-CA - fr-FR - hi-IN - it-IT - ja-JP - ko-KR - nl-BE - nl-NL - pt-BR - pt-PT - ro-RO - ru-RU - sk-SK - tr-TR - zh-CN BillToEnum: type: string enum: - parent - self GatewayTransactionTypeEnum: type: string enum: - moto KountDecisionEnum: type: string enum: - approve - decline - escalate - review CouponStateEnum: type: string enum: - expired - maxed_out - redeemable CouponDurationEnum: type: string enum: - forever - single_use - temporal TemporalUnitEnum: type: string enum: - day - month - week - year FreeTrialUnitEnum: type: string enum: - day - month - week RedemptionResourceEnum: type: string enum: - account - subscription CouponTypeEnum: type: string enum: - bulk - single_code DiscountTypeEnum: type: string enum: - fixed - free_trial - percent AddOnSourceEnum: type: string title: Add-on source description: | Used to determine where the associated add-on data is pulled from. If this value is set to `plan_add_on` or left blank, then add-on data will be pulled from the plan's add-ons. If the associated `plan` has `allow_any_item_on_subscriptions` set to `true` and this field is set to `item`, then the associated add-on data will be pulled from the site's item catalog. default: plan_add_on enum: - plan_add_on - item AddOnTypeEnum: type: string enum: - fixed - usage title: Add-on Type description: Whether the add-on type is fixed, or usage-based. AddOnTypeCreateEnum: type: string enum: - fixed - usage title: Add-on Type description: Whether the add-on type is fixed, or usage-based. default: fixed UsageTypeCreateEnum: type: string enum: - price - percentage title: Usage Type description: | Type of usage, required if `add_on_type` is `usage`. See our [Guide](https://developers.recurly.com/guides/usage-based-billing-guide.html) for an overview of how to configure usage add-ons. TierTypeEnum: type: string title: Tier type description: | The pricing model for the add-on. For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://developers.recurly.com/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models. default: flat enum: - flat - tiered - stairstep - volume CreditPaymentActionEnum: type: string enum: - payment - reduction - refund - write_off UserAccessEnum: type: string enum: - api_only - read_only - write RevenueScheduleTypeEnum: type: string enum: - at_range_end - at_range_start - evenly - never InvoiceTypeEnum: type: string enum: - charge - credit - legacy OriginEnum: type: string enum: - carryforward_credit - carryforward_gift_credit - credit - external_refund - gift_card - immediate_change - import - line_item_refund - open_amount_refund - prepayment - purchase - refund - renewal - termination - usage_correction - write_off InvoiceStateEnum: type: string enum: - open - pending - processing - past_due - paid - closed - failed - voided CollectionMethodEnum: type: string enum: - automatic - manual InvoiceRefundTypeEnum: type: string enum: - amount - line_items RefuneMethodEnum: type: string enum: - all_credit - all_transaction - credit_first - transaction_first ExternalPaymentMethodEnum: type: string enum: - ach - amazon - apple_pay - check - credit_card - eft - money_order - other - paypal - roku - sepadirectdebit - wire_transfer LineItemRevenueScheduleTypeEnum: type: string enum: - at_invoice - at_range_end - at_range_start - evenly - never LegacyCategoryEnum: type: string enum: - applied_credit - carryforward - charge - credit LineItemOriginEnum: type: string enum: - add_on - add_on_trial - carryforward - coupon - credit - debit - one_time - plan - plan_trial - setup_fee - prepayment FullCreditReasonCodeEnum: type: string enum: - general - gift_card - promotional - refund - service - write_off PartialCreditReasonCodeEnum: type: string enum: - general - promotional - service LineItemCreateOriginEnum: type: string enum: - external_gift_card - prepayment IntervalUnitEnum: type: string enum: - days - months AddressRequirementEnum: type: string enum: - full - none - streetzip - zip SiteModeEnum: type: string enum: - development - production - sandbox FeaturesEnum: type: string enum: - credit_memos - manual_invoicing - only_bill_what_changed - subscription_terms SubscriptionStateEnum: type: string enum: - active - canceled - expired - failed - future - paused TimeframeEnum: type: string enum: - bill_date - term_end ChangeTimeframeEnum: type: string enum: - bill_date - now - renewal - term_end TransactionTypeEnum: type: string enum: - authorization - capture - purchase - refund - verify TransactionOriginEnum: type: string enum: - api - chargeback - force_collect - hpp - merchant - recurly_admin - recurlyjs - recurring - refunded_externally - transparent TransactionStatusEnum: type: string enum: - chargeback - declined - error - pending - processing - scheduled - success - void CvvCheckEnum: type: string enum: - D - I - M - N - P - S - U - X AvsCheckEnum: type: string enum: - A - B - C - D - E - F - G - H - I - J - K - L - M - N - O - P - Q - R - S - T - U - V - W - X - Y - Z CouponCodeStateEnum: type: string enum: - expired - inactive - maxed_out - redeemable PaymentMethodEnum: type: string enum: - amazon - amazon_billing_agreement - apple_pay - bank_account_info - check - credit_card - eft - gateway_token - iban_bank_account - money_order - other - paypal - paypal_billing_agreement - roku - sepadirectdebit - wire_transfer - braintree_v_zero CardTypeEnum: type: string enum: - American Express - Dankort - Diners Club - Discover - Forbrugsforeningen - JCB - Laser - Maestro - MasterCard - Test Card - Union Pay - Unknown - Visa - Tarjeta Naranja AccountTypeEnum: type: string enum: - checking - savings 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 - transaction - unauthorized - unavailable_in_api_version - unknown_api_version - validation ErrorCategoryEnum: type: string enum: - three_d_secure_required - three_d_secure_action_required - amazon - api_error - approved - communication - configuration - duplicate - fraud - hard - invalid - not_enabled - not_supported - recurly - referral - skles - soft - unknown ErrorCodeEnum: type: string enum: - ach_cancel - ach_chargeback - ach_credit_return - ach_exception - ach_return - ach_transactions_not_supported - ach_validation_exception - amazon_amount_exceeded - amazon_declined_review - amazon_invalid_authorization_status - amazon_invalid_close_attempt - amazon_invalid_create_order_reference - amazon_invalid_order_status - amazon_not_authorized - amazon_order_not_modifiable - amazon_transaction_count_exceeded - api_error - approved - approved_fraud_review - authorization_already_captured - authorization_amount_depleted - authorization_expired - batch_processing_error - billing_agreement_already_accepted - billing_agreement_not_accepted - billing_agreement_not_found - billing_agreement_replaced - call_issuer - call_issuer_update_cardholder_data - cancelled - cannot_refund_unsettled_transactions - card_not_activated - card_type_not_accepted - cardholder_requested_stop - contact_gateway - contract_not_found - currency_not_supported - customer_canceled_transaction - cvv_required - declined - declined_card_number - declined_exception - declined_expiration_date - declined_missing_data - declined_saveable - declined_security_code - deposit_referenced_chargeback - direct_debit_type_not_accepted - duplicate_transaction - exceeds_daily_limit - exceeds_max_amount - expired_card - finbot_disconnect - finbot_unavailable - fraud_address - fraud_address_recurly - fraud_advanced_verification - fraud_gateway - fraud_generic - fraud_ip_address - fraud_manual_decision - fraud_risk_check - fraud_security_code - fraud_stolen_card - fraud_too_many_attempts - fraud_velocity - gateway_account_setup_incomplete - gateway_error - gateway_rate_limited - gateway_timeout - gateway_token_not_found - gateway_unavailable - gateway_validation_exception - insufficient_funds - invalid_account_number - invalid_amount - invalid_billing_agreement_status - invalid_card_number - invalid_data - invalid_email - invalid_gateway_access_token - invalid_gateway_configuration - invalid_issuer - invalid_login - invalid_merchant_type - invalid_name - invalid_payment_method - invalid_payment_method_hard - invalid_transaction - issuer_unavailable - merch_max_transaction_limit_exceeded - moneybot_disconnect - moneybot_unavailable - no_billing_information - no_gateway - no_gateway_found_for_transaction_amount - partial_approval - partial_credits_not_supported - payer_authentication_rejected - payment_cannot_void_authorization - payment_not_accepted - paypal_account_issue - paypal_cannot_pay_self - paypal_declined_use_alternate - paypal_expired_reference_id - paypal_hard_decline - paypal_invalid_billing_agreement - paypal_primary_declined - processor_not_available - processor_unavailable - recurly_credentials_not_found - recurly_error - recurly_failed_to_get_token - recurly_token_mismatch - recurly_token_not_found - reference_transactions_not_enabled - restricted_card - restricted_card_chargeback - rjs_token_expired - roku_invalid_card_number - roku_invalid_cib - roku_invalid_payment_method - roku_zip_code_mismatch - simultaneous - ssl_error - temporary_hold - three_d_secure_action_required - three_d_secure_action_result_token_mismatch - three_d_secure_authentication - three_d_secure_connection_error - three_d_secure_not_supported - too_many_attempts - total_credit_exceeds_capture - transaction_already_refunded - transaction_already_voided - transaction_cannot_be_authorized - transaction_cannot_be_refunded - transaction_cannot_be_refunded_currently - transaction_cannot_be_voided - transaction_failed_to_settle - transaction_not_found - transaction_service_v2_disconnect - transaction_service_v2_unavailable - transaction_settled - transaction_stale_at_gateway - try_again - unknown - unmapped_partner_error - vaultly_service_unavailable - zero_dollar_auth_not_supported ExportDates: type: object properties: object: type: string title: Object type readOnly: true dates: type: array items: type: string title: An array of dates that have available exports. ExportFiles: type: object properties: object: type: string title: Object type readOnly: true files: type: array items: "$ref": "#/components/schemas/ExportFile" ExportFile: type: object properties: name: type: string title: Filename description: Name of the export file. md5sum: type: string title: MD5 hash of the export file description: MD5 hash of the export file. href: type: string title: A link to the export file description: A presigned link to download the export file. TaxIdentifierTypeEnum: type: string enum: - cpf - cuit DunningCycleTypeEnum: type: string description: The type of invoice this cycle applies to. enum: - automatic - manual - trial AchTypeEnum: type: string description: The payment method type for a non-credit card based billing info. The value of `bacs` is the only accepted value (Bacs only) enum: - bacs AchAccountTypeEnum: type: string description: The bank account type. (ACH only) enum: - checking - savings