{"__v":0,"_id":"5595cb2dd4c23b0d00adf748","api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Authentication (HTTP Basic)\"\n}\n[/block]\nRecurly uses HTTP Basic Authentication—your [API key](https://app.recurly.com/go/developer/api_access) is securely encrypted by the SSL channel.\n\nIf you are testing the API calls via the command line with cURL, try:\n\n```\ncurl -H 'Accept: application/xml' \\\n     -H 'Content-Type: application/xml; charset=utf-8' \\\n     -u [API Key]: https://[subdomain].recurly.com/v2/accounts\n```\n\nIn most programming languages, the API key can be specified in the authentication section of request. If your language requires a username and password, enter the API key in the username and set the password to an empty string.\n\nREGENERATING AN API KEY\nYour API key can be regenerated by clicking on the Regenerate button on the [API credentials](https://app.recurly.com/go/developer/api_access) page.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"Only one API key may be active on an account at a time. If you choose to regenerate your API key, your services will not work until you’ve updated all references to your API key. There is only one API key per Recurly site. Regenerating the key will regenerate it for all users.\\n\\nWhen regenerating your API key, you may choose to expire the prior key immediately or after 12 hours. The 12 hour delay allows you to create a new key to replace your existing API key and maintain API access continuity.\",\n  \"title\": \"Note\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Calculating your own authorization header\"\n}\n[/block]\nMost programming languages encode the authorization header automatically. With HTTP Basic Authentication, the `Authorization` header is a string containing a Base-64 encoded username and password. In the case of Recurly’s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string.\n\n```\n\"Authorization\": \"Basic \" + base64_encode(API Key)\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Additional headers\"\n}\n[/block]\nACCEPT HEADER\nRecurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML:\n\n```\nAccept: application/xml\n```\n\nCONTENT-TYPE HEADER\nWhen sending data to Recurly in a POST or PUT request, your request must specify the content type of your request:\n\n```\nContent-Type: application/xml; charset=utf-8\n```\n\nIf your XML request is invalid, the API will respond with a status code 400 Bad Request. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.","category":"5595cb2ad4c23b0d00adf6e5","createdAt":"2015-06-10T22:06:37.745Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"getting-started","sync_unique":"","title":"Authentication","type":"basic","updates":["5595c7e9f44370190028891c"],"user":"5564a0073a61a72f0067cb22","version":"5595cb29d4c23b0d00adf6e3"}

Authentication


[block:api-header] { "type": "basic", "title": "API Authentication (HTTP Basic)" } [/block] Recurly uses HTTP Basic Authentication—your [API key](https://app.recurly.com/go/developer/api_access) is securely encrypted by the SSL channel. If you are testing the API calls via the command line with cURL, try: ``` curl -H 'Accept: application/xml' \ -H 'Content-Type: application/xml; charset=utf-8' \ -u [API Key]: https://[subdomain].recurly.com/v2/accounts ``` In most programming languages, the API key can be specified in the authentication section of request. If your language requires a username and password, enter the API key in the username and set the password to an empty string. REGENERATING AN API KEY Your API key can be regenerated by clicking on the Regenerate button on the [API credentials](https://app.recurly.com/go/developer/api_access) page. [block:callout] { "type": "danger", "body": "Only one API key may be active on an account at a time. If you choose to regenerate your API key, your services will not work until you’ve updated all references to your API key. There is only one API key per Recurly site. Regenerating the key will regenerate it for all users.\n\nWhen regenerating your API key, you may choose to expire the prior key immediately or after 12 hours. The 12 hour delay allows you to create a new key to replace your existing API key and maintain API access continuity.", "title": "Note" } [/block] [block:api-header] { "type": "basic", "title": "Calculating your own authorization header" } [/block] Most programming languages encode the authorization header automatically. With HTTP Basic Authentication, the `Authorization` header is a string containing a Base-64 encoded username and password. In the case of Recurly’s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string. ``` "Authorization": "Basic " + base64_encode(API Key) ``` [block:api-header] { "type": "basic", "title": "Additional headers" } [/block] ACCEPT HEADER Recurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML: ``` Accept: application/xml ``` CONTENT-TYPE HEADER When sending data to Recurly in a POST or PUT request, your request must specify the content type of your request: ``` Content-Type: application/xml; charset=utf-8 ``` If your XML request is invalid, the API will respond with a status code 400 Bad Request. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.
View all 71 endpoints
[block:api-header] { "type": "basic", "title": "API Authentication (HTTP Basic)" } [/block] Recurly uses HTTP Basic Authentication—your [API key](https://app.recurly.com/go/developer/api_access) is securely encrypted by the SSL channel. If you are testing the API calls via the command line with cURL, try: ``` curl -H 'Accept: application/xml' \ -H 'Content-Type: application/xml; charset=utf-8' \ -u [API Key]: https://[subdomain].recurly.com/v2/accounts ``` In most programming languages, the API key can be specified in the authentication section of request. If your language requires a username and password, enter the API key in the username and set the password to an empty string. REGENERATING AN API KEY Your API key can be regenerated by clicking on the Regenerate button on the [API credentials](https://app.recurly.com/go/developer/api_access) page. [block:callout] { "type": "danger", "body": "Only one API key may be active on an account at a time. If you choose to regenerate your API key, your services will not work until you’ve updated all references to your API key. There is only one API key per Recurly site. Regenerating the key will regenerate it for all users.\n\nWhen regenerating your API key, you may choose to expire the prior key immediately or after 12 hours. The 12 hour delay allows you to create a new key to replace your existing API key and maintain API access continuity.", "title": "Note" } [/block] [block:api-header] { "type": "basic", "title": "Calculating your own authorization header" } [/block] Most programming languages encode the authorization header automatically. With HTTP Basic Authentication, the `Authorization` header is a string containing a Base-64 encoded username and password. In the case of Recurly’s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string. ``` "Authorization": "Basic " + base64_encode(API Key) ``` [block:api-header] { "type": "basic", "title": "Additional headers" } [/block] ACCEPT HEADER Recurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML: ``` Accept: application/xml ``` CONTENT-TYPE HEADER When sending data to Recurly in a POST or PUT request, your request must specify the content type of your request: ``` Content-Type: application/xml; charset=utf-8 ``` If your XML request is invalid, the API will respond with a status code 400 Bad Request. This commonly occurs when ampersands are not correctly encoded in the text of your request. Please inspect the body of the response for more details regarding the error.
{"__v":0,"_id":"5595cb2dd4c23b0d00adf747","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"## SUCCESSFUL STATUS CODES (2XX)\n`200 OK`\nThe request was successful.\n`201 Created`\nThe resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc.\n`204 No Content`\nThe request was successful and there is no response body.\n\n## CLIENT ERROR STATUS CODES (4XX)\n`400 Bad Request`\nThe request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.\n`401 Unauthorized`\nYour API key is missing or invalid.\n`402 Payment Required`\nYour Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices.\n`403 Forbidden`\nThe login is attempting to perform an action it does not have privileges to access. Verify your login credentials are for the appropriate account.\n`404 Not Found`\nThe resource was not found with the given identifier. The response body will explain which resource was not found.\n`405 Method Not Allowed`\nThe requested method is not valid at the given URL.\n`406 Not Acceptable`\nThe request's Accept header is not set to application/xml.\n`412 Precondition Failed`\nThe request was unsuccessful because a condition was not met. For example, this message may be returned if you attempt to cancel a subscription for an account that has no subscription.\n`422 Unprocessable Entity`\nCould not process a POST or PUT request because the request is invalid. See the response body for more details.\n`429 Too many Requests`\nYou have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour.\n\n## SERVER ERROR STATUS CODES (5XX)\n`500 Internal Server Error`\nThe server encountered an error while processing your request and failed.\n`502 Gateway Error`\nThe load balancer or web server has trouble connecting to the Recurly app. Please try the request again.\n`503 Service Unavailable`\nThe service is temporarily unavailable. Please try the request again.\n\n##FUTURE COMPATIBILITY\nFor future compatibility, please interpret the following status code ranges:\n\n**200–299** as success,\n**400–499** as client request errors,\n**500–599** as server errors\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"404 Not found responses\"\n}\n[/block]\nWhen a lookup, update, or delete request is requested on an object that does not exist, the server returns `404 Not Found`:\n\n```\nStatus: 404 Not Found\nContent-Type: application/xml; charset=utf-8\n```\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<error>\n  <symbol>not_found</symbol>\n  <description>The record could not be located.</description>\n</error>\n```","category":"5595cb2ad4c23b0d00adf6e5","createdAt":"2015-06-10T22:06:26.211Z","excerpt":"Every request includes an HTTP status code with the result. The status code should examined before the response. In most error cases, the response body will contain an errors XML document with more details.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"welcome","sync_unique":"","title":"HTTP Status Codes","type":"basic","updates":[],"user":"5564a0073a61a72f0067cb22","version":"5595cb29d4c23b0d00adf6e3"}

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should examined before the response. In most error cases, the response body will contain an errors XML document with more details.

## SUCCESSFUL STATUS CODES (2XX) `200 OK` The request was successful. `201 Created` The resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc. `204 No Content` The request was successful and there is no response body. ## CLIENT ERROR STATUS CODES (4XX) `400 Bad Request` The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error. `401 Unauthorized` Your API key is missing or invalid. `402 Payment Required` Your Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices. `403 Forbidden` The login is attempting to perform an action it does not have privileges to access. Verify your login credentials are for the appropriate account. `404 Not Found` The resource was not found with the given identifier. The response body will explain which resource was not found. `405 Method Not Allowed` The requested method is not valid at the given URL. `406 Not Acceptable` The request's Accept header is not set to application/xml. `412 Precondition Failed` The request was unsuccessful because a condition was not met. For example, this message may be returned if you attempt to cancel a subscription for an account that has no subscription. `422 Unprocessable Entity` Could not process a POST or PUT request because the request is invalid. See the response body for more details. `429 Too many Requests` You have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour. ## SERVER ERROR STATUS CODES (5XX) `500 Internal Server Error` The server encountered an error while processing your request and failed. `502 Gateway Error` The load balancer or web server has trouble connecting to the Recurly app. Please try the request again. `503 Service Unavailable` The service is temporarily unavailable. Please try the request again. ##FUTURE COMPATIBILITY For future compatibility, please interpret the following status code ranges: **200–299** as success, **400–499** as client request errors, **500–599** as server errors [block:api-header] { "type": "basic", "title": "404 Not found responses" } [/block] When a lookup, update, or delete request is requested on an object that does not exist, the server returns `404 Not Found`: ``` Status: 404 Not Found Content-Type: application/xml; charset=utf-8 ``` ``` <?xml version="1.0" encoding="UTF-8"?> <error> <symbol>not_found</symbol> <description>The record could not be located.</description> </error> ```
## SUCCESSFUL STATUS CODES (2XX) `200 OK` The request was successful. `201 Created` The resource was successfully created. Confirms a success when creating a new account, credit, subscription, etc. `204 No Content` The request was successful and there is no response body. ## CLIENT ERROR STATUS CODES (4XX) `400 Bad Request` The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error. `401 Unauthorized` Your API key is missing or invalid. `402 Payment Required` Your Recurly account is in production mode but is not in good standing. Please pay any outstanding invoices. `403 Forbidden` The login is attempting to perform an action it does not have privileges to access. Verify your login credentials are for the appropriate account. `404 Not Found` The resource was not found with the given identifier. The response body will explain which resource was not found. `405 Method Not Allowed` The requested method is not valid at the given URL. `406 Not Acceptable` The request's Accept header is not set to application/xml. `412 Precondition Failed` The request was unsuccessful because a condition was not met. For example, this message may be returned if you attempt to cancel a subscription for an account that has no subscription. `422 Unprocessable Entity` Could not process a POST or PUT request because the request is invalid. See the response body for more details. `429 Too many Requests` You have made too many API requests in the last hour. Future API requests will be ignored until the beginning of the next hour. ## SERVER ERROR STATUS CODES (5XX) `500 Internal Server Error` The server encountered an error while processing your request and failed. `502 Gateway Error` The load balancer or web server has trouble connecting to the Recurly app. Please try the request again. `503 Service Unavailable` The service is temporarily unavailable. Please try the request again. ##FUTURE COMPATIBILITY For future compatibility, please interpret the following status code ranges: **200–299** as success, **400–499** as client request errors, **500–599** as server errors [block:api-header] { "type": "basic", "title": "404 Not found responses" } [/block] When a lookup, update, or delete request is requested on an object that does not exist, the server returns `404 Not Found`: ``` Status: 404 Not Found Content-Type: application/xml; charset=utf-8 ``` ``` <?xml version="1.0" encoding="UTF-8"?> <error> <symbol>not_found</symbol> <description>The record could not be located.</description> </error> ```
{"__v":3,"_id":"5595cb2dd4c23b0d00adf74a","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Number of Records\"\n}\n[/block]\nEndpoints that return a list of resources will include a header indicating the total number of records available. This is specified with the `X-Records` header. E.g., for an endpoint with 14 records:\n\n```\nX-Records: 14\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Next\"\n}\n[/block]\nThe amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a `per_page` query parameter, e.g. to return 200 accounts at a time:\n\n```\nhttps://your-subdomain.recurly.com/v2/accounts?per_page=200\n```\n\nWhen there are more records remaining than fit in the current response, the `Link` header is specified with the URI to the next page of results.\n\n```\nStatus: 200 OK\nX-Records: 204\nLink: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel=\"next\"\nETag: \"a4b0568a2278bc591ceb64b31547eb78\"\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Cursors\"\n}\n[/block]\nThe cursor parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Previous Pages\"\n}\n[/block]\nAfter paginating beyond the first page of results, the Link header will include a link to return to the first page of results (`rel=\"start\"`) and the previous page (`rel=\"prev\"`):\n\n```\nStatus: 200 OK\nX-Records: 204\nLink: <https://your-subdomain.recurly.com/v2/transactions>; rel=\"start\",\n  <https://your-subdomain.recurly.com/v2/transactions?cursor=-1318344434>; rel=\"prev\",\n  <https://your-subdomain.recurly.com/v2/transactions?cursor=1318388868>; rel=\"next\"\nETag: \"c7431fcfc386fd59ee6c3c2e9ac2a30c\"\n```","category":"5595cb2ad4c23b0d00adf6e5","createdAt":"2015-06-15T22:48:39.567Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"pagination","sync_unique":"","title":"Pagination","type":"basic","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

Pagination


[block:api-header] { "type": "basic", "title": "Number of Records" } [/block] Endpoints that return a list of resources will include a header indicating the total number of records available. This is specified with the `X-Records` header. E.g., for an endpoint with 14 records: ``` X-Records: 14 ``` [block:api-header] { "type": "basic", "title": "Next" } [/block] The amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a `per_page` query parameter, e.g. to return 200 accounts at a time: ``` https://your-subdomain.recurly.com/v2/accounts?per_page=200 ``` When there are more records remaining than fit in the current response, the `Link` header is specified with the URI to the next page of results. ``` Status: 200 OK X-Records: 204 Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel="next" ETag: "a4b0568a2278bc591ceb64b31547eb78" ``` [block:api-header] { "type": "basic", "title": "Cursors" } [/block] The cursor parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests. [block:api-header] { "type": "basic", "title": "Previous Pages" } [/block] After paginating beyond the first page of results, the Link header will include a link to return to the first page of results (`rel="start"`) and the previous page (`rel="prev"`): ``` Status: 200 OK X-Records: 204 Link: <https://your-subdomain.recurly.com/v2/transactions>; rel="start", <https://your-subdomain.recurly.com/v2/transactions?cursor=-1318344434>; rel="prev", <https://your-subdomain.recurly.com/v2/transactions?cursor=1318388868>; rel="next" ETag: "c7431fcfc386fd59ee6c3c2e9ac2a30c" ```
[block:api-header] { "type": "basic", "title": "Number of Records" } [/block] Endpoints that return a list of resources will include a header indicating the total number of records available. This is specified with the `X-Records` header. E.g., for an endpoint with 14 records: ``` X-Records: 14 ``` [block:api-header] { "type": "basic", "title": "Next" } [/block] The amount of records returns within a single API request defaults to 50. It may be changed to a maximum of 200 using a `per_page` query parameter, e.g. to return 200 accounts at a time: ``` https://your-subdomain.recurly.com/v2/accounts?per_page=200 ``` When there are more records remaining than fit in the current response, the `Link` header is specified with the URI to the next page of results. ``` Status: 200 OK X-Records: 204 Link: <https://your-subdomain.recurly.com/v2/accounts?cursor=1304958672>; rel="next" ETag: "a4b0568a2278bc591ceb64b31547eb78" ``` [block:api-header] { "type": "basic", "title": "Cursors" } [/block] The cursor parameter is a time-based pointer indicating where to resume the results. By using a cursor instead of page numbers, the API avoids returning duplicate records in the case where additional resources are added between pagination requests. [block:api-header] { "type": "basic", "title": "Previous Pages" } [/block] After paginating beyond the first page of results, the Link header will include a link to return to the first page of results (`rel="start"`) and the previous page (`rel="prev"`): ``` Status: 200 OK X-Records: 204 Link: <https://your-subdomain.recurly.com/v2/transactions>; rel="start", <https://your-subdomain.recurly.com/v2/transactions?cursor=-1318344434>; rel="prev", <https://your-subdomain.recurly.com/v2/transactions?cursor=1318388868>; rel="next" ETag: "c7431fcfc386fd59ee6c3c2e9ac2a30c" ```
{"__v":0,"_id":"5595cb2dd4c23b0d00adf74b","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"body":"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:\n\n* Sandbox sites: 400 requests/min. All requests count towards the rate limit.\n* Production sites: 1,000 requests/min. Only GET requests count towards the rate limit.\n\nOnce 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.\n\nThe 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.\n\nIf an API request exceeds the rate limit, the API returns a 429 status code indicating `Too Many Requests`. If your business needs a higher limit, please contact support.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Headers\"\n}\n[/block]\nEvery authenticated API request returns headers with your current rate limit information. Your requests’ rate limit headers may look like:\n\n```\nX-RateLimit-Limit: 5000\nX-RateLimit-Remaining: 4999\nX-RateLimit-Reset: 1414622019\n```\n\nThe `X-RateLimit-Limit` is your total request limit during the 5 minute window (e.g. requests/min * 5 min). The `X-RateLimit-Remaining` indicates the number of requests remaining until your requests will be denied. Finally, the `X-RateLimit-Reset` header contains a timestamp for when the current window will completely reset assuming no further API requests are made.","category":"5595cb2ad4c23b0d00adf6e5","createdAt":"2015-06-15T22:49:59.038Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"rate-limits","sync_unique":"","title":"Rate Limits","type":"basic","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

Rate Limits


In order to provide a fast response time to all our customers, we may rate limit excessive requests. By default, new Recurly sites have the following API rate limits: * Sandbox sites: 400 requests/min. All requests count towards the rate limit. * Production sites: 1,000 requests/min. Only GET 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 returns a 429 status code indicating `Too Many Requests`. If your business needs a higher limit, please contact support. [block:api-header] { "type": "basic", "title": "HTTP Headers" } [/block] Every authenticated API request returns headers with your current rate limit information. Your requests’ rate limit headers may look like: ``` X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4999 X-RateLimit-Reset: 1414622019 ``` The `X-RateLimit-Limit` is your total request limit during the 5 minute window (e.g. requests/min * 5 min). The `X-RateLimit-Remaining` indicates the number of requests remaining until your requests will be denied. Finally, the `X-RateLimit-Reset` header contains a timestamp for when the current window will completely reset assuming no further API requests are made.
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 returns a 429 status code indicating `Too Many Requests`. If your business needs a higher limit, please contact support. [block:api-header] { "type": "basic", "title": "HTTP Headers" } [/block] Every authenticated API request returns headers with your current rate limit information. Your requests’ rate limit headers may look like: ``` X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4999 X-RateLimit-Reset: 1414622019 ``` The `X-RateLimit-Limit` is your total request limit during the 5 minute window (e.g. requests/min * 5 min). The `X-RateLimit-Remaining` indicates the number of requests remaining until your requests will be denied. Finally, the `X-RateLimit-Reset` header contains a timestamp for when the current window will completely reset assuming no further API requests are made.
{"__v":1,"_id":"5595cb2dd4c23b0d00adf74c","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"If the requested create, update, or delete cannot be performed due to validation errors, the server returns a `422 Unprocessable Entity` response with an array of the validation errors:\n\n```\nStatus: 422 Unprocessable Entity\nContent-Type: application/xml; charset=utf-8\n```\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<errors>\n  <error field=\"model_name.field_name\" symbol=\"not_a_number\" lang=\"en-US\">is not a number</error>\n</errors>\n```","category":"5595cb2ad4c23b0d00adf6e5","createdAt":"2015-06-15T22:50:50.788Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"api-validation-errors","sync_unique":"","title":"API Validation Errors","type":"basic","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

API Validation Errors


If the requested create, update, or delete cannot be performed due to validation errors, the server returns a `422 Unprocessable Entity` response with an array of the validation errors: ``` Status: 422 Unprocessable Entity Content-Type: application/xml; charset=utf-8 ``` ``` <?xml version="1.0" encoding="UTF-8"?> <errors> <error field="model_name.field_name" symbol="not_a_number" lang="en-US">is not a number</error> </errors> ```
If the requested create, update, or delete cannot be performed due to validation errors, the server returns a `422 Unprocessable Entity` response with an array of the validation errors: ``` Status: 422 Unprocessable Entity Content-Type: application/xml; charset=utf-8 ``` ``` <?xml version="1.0" encoding="UTF-8"?> <errors> <error field="model_name.field_name" symbol="not_a_number" lang="en-US">is not a number</error> </errors> ```
{"__v":2,"_id":"5595cb2bd4c23b0d00adf6f5","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Recurly has a variety of integrations you should check out!\n\n[Recurly.js](https://docs.recurly.com/js/)\n\n[Webhooks API](https://recurly.readme.io/v2.0/page/webhooks)\n\n[Customer Imports](https://recurly.readme.io/v2.0/page/customer-imports)","category":"5595cb2ad4c23b0d00adf6e6","createdAt":"2015-06-26T18:21:30.595Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"integrations","sync_unique":"","title":"Integrations","type":"basic","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

Integrations


Recurly has a variety of integrations you should check out! [Recurly.js](https://docs.recurly.com/js/) [Webhooks API](https://recurly.readme.io/v2.0/page/webhooks) [Customer Imports](https://recurly.readme.io/v2.0/page/customer-imports)
Recurly has a variety of integrations you should check out! [Recurly.js](https://docs.recurly.com/js/) [Webhooks API](https://recurly.readme.io/v2.0/page/webhooks) [Customer Imports](https://recurly.readme.io/v2.0/page/customer-imports)
{"__v":9,"_id":"5595cb2bd4c23b0d00adf70c","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Recurly has a variety of official client libraries you should check out!\n\n[PHP](https://recurly.readme.io/v2.0/page/php)\n[Ruby](https://recurly.readme.io/v2.0/page/ruby)\n[Python](https://recurly.readme.io/v2.0/page/python)\n[.Net](https://recurly.readme.io/v2.0/page/net)\niOS – [Github](https://github.com/recurly/recurly-client-ios) | [Documentation](http://cocoadocs.org/docsets/RecurlySDK/)\nAndroid – [Github](https://github.com/recurly/recurly-client-android) | [Documentation](https://docs.recurly.com/mobile/android-sdk/index.html)\n\nThere are also some unofficial libraries created by our users\n\n[Java](https://github.com/killbilling/recurly-java-library)\n[GO](https://github.com/cgerrior/gorecurly)\n[Node.js](https://github.com/cgerrior/node-recurly)","category":"5595cb2ad4c23b0d00adf6ec","createdAt":"2015-06-26T18:25:56.960Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"client-libraries","sync_unique":"","title":"Client Libraries","type":"basic","updates":["55940e20fd29b92300c262bf","55b2bfc0a74a380d00e290a6","55b2c0466862a10d00887adf","55bbb926a8400c2d00873f2a"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

Client Libraries


Recurly has a variety of official client libraries you should check out! [PHP](https://recurly.readme.io/v2.0/page/php) [Ruby](https://recurly.readme.io/v2.0/page/ruby) [Python](https://recurly.readme.io/v2.0/page/python) [.Net](https://recurly.readme.io/v2.0/page/net) iOS – [Github](https://github.com/recurly/recurly-client-ios) | [Documentation](http://cocoadocs.org/docsets/RecurlySDK/) Android – [Github](https://github.com/recurly/recurly-client-android) | [Documentation](https://docs.recurly.com/mobile/android-sdk/index.html) There are also some unofficial libraries created by our users [Java](https://github.com/killbilling/recurly-java-library) [GO](https://github.com/cgerrior/gorecurly) [Node.js](https://github.com/cgerrior/node-recurly)
Recurly has a variety of official client libraries you should check out! [PHP](https://recurly.readme.io/v2.0/page/php) [Ruby](https://recurly.readme.io/v2.0/page/ruby) [Python](https://recurly.readme.io/v2.0/page/python) [.Net](https://recurly.readme.io/v2.0/page/net) iOS – [Github](https://github.com/recurly/recurly-client-ios) | [Documentation](http://cocoadocs.org/docsets/RecurlySDK/) Android – [Github](https://github.com/recurly/recurly-client-android) | [Documentation](https://docs.recurly.com/mobile/android-sdk/index.html) There are also some unofficial libraries created by our users [Java](https://github.com/killbilling/recurly-java-library) [GO](https://github.com/cgerrior/gorecurly) [Node.js](https://github.com/cgerrior/node-recurly)
{"__v":0,"_id":"55e4b6214792160d0046218c","api":{"auth":"required","examples":{"codes":[{"language":"text","code":""}]},"params":[{"_id":"557f45d07eafa719001d1c2b","required":false,"desc":"The URL of adjustments for the specified account","default":"","type":"string","name":"adjustments"},{"_id":"557f45d07eafa719001d1c2a","required":false,"desc":"The URL of billing info for the specified account","default":"","type":"string","name":"billing_info"},{"_id":"557f45d07eafa719001d1c29","required":false,"desc":"The URL of invoices for the specified account","default":"","type":"string","name":"invoices"},{"_id":"55e4aa556f190c1900a40881","required":false,"desc":"The URL of the coupon redemption for the specified account","default":"","type":"string","name":"redemption"},{"_id":"55e4aa556f190c1900a40880","required":false,"desc":"The URL of subscriptions for the specified account","default":"","type":"string","name":"subscriptions"},{"_id":"55e4aa556f190c1900a4087f","required":false,"desc":"The URL of transactions for the specified account","default":"","type":"string","name":"transactions"},{"_id":"55e4aa556f190c1900a4087e","required":false,"desc":"The unique identifier of the account","default":"","type":"string","name":"account_code"},{"_id":"55e4aa556f190c1900a4087d","required":false,"desc":"The state of accounts to return: `active` or `closed`","default":"","type":"string","name":"state"},{"_id":"55e4aa556f190c1900a4087c","required":false,"desc":"The username of the account","default":"","type":"string","name":"username"},{"_id":"55e4aa556f190c1900a4087b","required":false,"desc":"The email address of the account","default":"","type":"string","name":"email"},{"_id":"55e4aa556f190c1900a4087a","required":false,"desc":"The first name of the account","default":"","type":"string","name":"first_name"},{"_id":"55e4aa556f190c1900a40879","required":false,"desc":"The last name of the account","default":"","type":"string","name":"last_name"},{"_id":"55e4aa556f190c1900a40878","required":false,"desc":"The company name of the account","default":"","type":"string","name":"company_name"},{"_id":"55e4aa556f190c1900a40877","required":false,"desc":"The VAT number of the account (to avoid having the VAT applied)","default":"","type":"string","name":"vat_number"},{"_id":"55e4aa556f190c1900a40876","required":false,"desc":"The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account","default":"","type":"boolean","name":"tax_exempt"},{"_id":"55e4aa556f190c1900a40875","required":false,"desc":"The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`","default":"","type":"object","name":"address"},{"_id":"55e4aa556f190c1900a40874","required":false,"desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale","default":"","type":"string","name":"accept_language"},{"_id":"55e4aa556f190c1900a40873","required":false,"desc":"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`","default":"","type":"string","name":"hosted_login_token"},{"_id":"55e4aa556f190c1900a40872","required":false,"desc":"The DateTime the account was created in Recurly","default":"","type":"datetime","name":"created_at"}],"results":{"codes":[{"status":200,"language":"xml","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name></company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"></phone>\n  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-10-25T12:00:00Z</created_at>\n</account>","name":""}]},"settings":"","url":"/accounts"},"body":"","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-08-31T20:16:33.273Z","excerpt":"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.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"account-object","sync_unique":"","title":"Account Object","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getAccount Object

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.

adjustments:
String
The URL of adjustments for the specified account
billing_info:
String
The URL of billing info for the specified account
invoices:
String
The URL of invoices for the specified account
redemption:
String
The URL of the coupon redemption for the specified account
subscriptions:
String
The URL of subscriptions for the specified account
transactions:
String
The URL of transactions for the specified account
account_code:
String
The unique identifier of the account
state:
String
The state of accounts to return: `active` or `closed`
username:
String
The username of the account
email:
String
The email address of the account
first_name:
String
The first name of the account
last_name:
String
The last name of the account
company_name:
String
The company name of the account
vat_number:
String
The VAT number of the account (to avoid having the VAT applied)
tax_exempt:
Boolean
The tax status of the account. `true` exempts tax on the account, `false` applies tax on the account
address:
Object
The nested address information of the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`
accept_language:
String
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale
hosted_login_token:
String
The unique token for automatically logging the account in to the hosted management pages. You may automatically log the user into their hosted management pages by directing the user to: `https://:subdomain.recurly.com/account/:hosted_login_token`
created_at:
DateTime
The DateTime the account was created in Recurly

Definition

{{ api_url }}{{ page_api_url }}

Result Format



{"__v":7,"_id":"5595cb2bd4c23b0d00adf6f7","api":{"auth":"required","examples":{"codes":[{"name":"","code":"<?php\n$accounts = Recurly_AccountList::getActive();\nforeach ($accounts as $account) {\n  print \"Account: $account\\n\";\n}\n?>","language":"php"},{"code":"Recurly::Account.find_each do |account|\n  puts \"Account: #{account.inspect}\"\nend","language":"ruby"},{"code":"#client version <= 2.1.5\naccounts = Account.all()\nwhile accounts:\n    for account in accounts:\n        print 'Account: %s' % account\n    try:\n        accounts = accounts.next_page()\n    except PageError:\n        accounts = ()\n\n#client version 2.1.6+\nfor account in Account.all():\n    print 'Account: %s' % account","language":"python"},{"code":"using System.Linq;\n\nvar accounts = Accounts.List();\nwhile (accounts.Any())\n{\n\tforeach (var account in accounts)\n\t\tConsole.WriteLine(account);\n\taccounts = accounts.Next;\n}","language":"csharp","name":null}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<accounts type=\"array\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n    <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n    <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n    <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n    <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n    <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n    <account_code>1</account_code>\n    <state>active</state>\n    <username nil=\"nil\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name></company_name>\n    <vat_number nil=\"nil\"></vat_number>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <address>\n      <address1>123 Main St.</address1>\n      <address2 nil=\"nil\"></address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94105</zip>\n      <country>US</country>\n      <phone nil=\"nil\"></phone>\n    </address>\n    <accept_language nil=\"nil\"></accept_language>\n    <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n    <created_at type=\"datetime\">2015-08-25T12:00:00Z</created_at>\n  </account>\n  <!-- Continued... -->\n</accounts>","name":""}]},"settings":"","url":"/accounts"},"body":"","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T21:38:24.720Z","excerpt":"Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-accounts","sync_unique":"","title":"List Accounts","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getList Accounts

Returns a list of accounts on your site. Results are ordered by the time created, sorted by newest first.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2bd4c23b0d00adf6f8","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $account = Recurly_Account::get('1');\n  print \"Account: $account\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found.\\n\";\n}\n","name":""},{"language":"ruby","code":"begin\n  account = Recurly::Account.find '1'\n  puts \"Account: #{account.inspect}\"\nrescue Recurly::Resource::NotFound => e\n  puts e.message\nend"},{"language":"python","code":"try:\n  account = Account.get('1')\n  print \"Account: %s\" % account\nexcept NotFoundError:\n  print \"Account not found.\\n\""},{"language":"csharp","code":"try\n{\n\tvar account = Accounts.Get(\"1\");\n\tConsole.WriteLine(\"Account \" + account);\n}\ncatch (NotFoundException e)\n{\n\tConsole.WriteLine(\"Account not found.\");\n}"}]},"params":[{"_id":"557f478deb75d80d00af4086","required":true,"desc":"The unique account identifier","default":"","type":"string","name":"account_code"}],"results":{"codes":[{"status":200,"language":"xml","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name></company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"></phone>\n  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-08-25T12:00:00Z</created_at>\n</account>","name":""}]},"settings":"","url":"/accounts/:account_code"},"body":"","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T21:45:49.420Z","excerpt":"Returns information about a single account.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"get-account","sync_unique":"","title":"Get Account","type":"get","updates":["55bbdd4e1067fc1700510eed"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getGet Account

Returns information about a single account.

account_code:
required
String
The unique account identifier

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf6f6","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $account = new Recurly_Account('b6f5783');\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n  $account->create();\n\n  print \"Account: $account\\n\";\n\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Account: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.create(\n  :account_code => '1',\n  :email        => 'verena@example.com',\n  :first_name   => 'Verena',\n  :last_name    => 'Example'\n)","language":"ruby"},{"code":"account = Account(account_code='1')\naccount.email = 'verena@example.com'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\naccount.save()","language":"python"},{"code":"var account = new Account(\"1\")\n{\n  Email = \"verena@example.com\",\n  FirstName = \"Verena\",\n  LastName = \"Example\"\n};\naccount.Create();","language":"csharp"},{"language":"xml","code":"<account>\n  <account_code>1</account_code>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <address>\n    <address1>123 Main St.</address1>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n  </address>\n</account>"}]},"params":[{"_id":"557f3209e211d20d00601425","default":"","desc":"A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot character. Max of 50 characters","name":"account_code","required":true,"type":"string"},{"_id":"557f3209e211d20d00601424","default":"","desc":"The username for the account, ignore if you do not use usernames. Max of 255 characters","name":"username","required":false,"type":"string"},{"_id":"557f3209e211d20d00601423","default":"","desc":"The email address for the account","name":"email","required":false,"type":"string"},{"_id":"557f32d1e211d20d00601430","default":"","desc":"The first name for the account. Max of 255 characters","name":"first_name","required":false,"type":"string"},{"_id":"557f32d1e211d20d0060142f","default":"","desc":"The last name for the account.  Max of 255 characters","name":"last_name","required":false,"type":"string"},{"_id":"557f32d1e211d20d0060142e","default":"","desc":"The company name for the account. Max of 255 characters","name":"company_name","required":false,"type":"string"},{"_id":"557f32d1e211d20d0060142d","default":"","desc":"The VAT number to avoid having the VAT applied (if applicable)","name":"vat_number","required":false,"type":"string"},{"_id":"557f32d1e211d20d0060142c","default":"","desc":"The tax status for the account","name":"tax_exempt","required":false,"type":"boolean"},{"_id":"557f32d1e211d20d0060142b","default":"","desc":"The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive","name":"entity_use_code","required":false,"type":"string"},{"_id":"557f32d1e211d20d0060142a","default":"","desc":"The nested billing information. If present, the account will only be created after the billing information is validated","name":"billing_info","required":false,"type":"object"},{"_id":"557f32d1e211d20d00601429","default":"","desc":"The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`","name":"address","required":false,"type":"object"},{"_id":"557f32d1e211d20d00601428","default":"","desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale","name":"accept_language","required":false,"type":"string"}],"results":{"codes":[{"name":"","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name></company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"></phone>\n  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-10-25T12:00:00Z</created_at>\n</account>","language":"xml","status":201}]},"settings":"","url":"/accounts"},"body":"","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T20:12:03.880Z","excerpt":"Creates a new account. You may optionally include billing information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-an-account","sync_unique":"","title":"Create an Account","type":"post","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate an Account

Creates a new account. You may optionally include billing information.

account_code:
required
String
A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot character. Max of 50 characters
username:
String
The username for the account, ignore if you do not use usernames. Max of 255 characters
email:
String
The email address for the account
first_name:
String
The first name for the account. Max of 255 characters
last_name:
String
The last name for the account. Max of 255 characters
company_name:
String
The company name for the account. Max of 255 characters
vat_number:
String
The VAT number to avoid having the VAT applied (if applicable)
tax_exempt:
Boolean
The tax status for the account
entity_use_code:
String
The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive
billing_info:
Object
The nested billing information. If present, the account will only be created after the billing information is validated
address:
Object
The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`
accept_language:
String
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf6f9","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $account = Recurly_Account::get('b6f5783');\n  $account->company_name = 'New Company Name';\n  $account->update();\n\n  print \"Account: $account\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.find('account_1')\naccount.company_name = 'New Company Name'\naccount.save","language":"ruby"},{"code":"account = Account.get('account_1')\naccount.company_name = 'New Company Name'\naccount.save()","language":"python"},{"code":"var account = Account.Get(\"account_1\");\naccount.CompanyName = 'New Company Name'\naccount.Update();","language":"csharp"},{"code":"<account>\n  <company_name>New Company Name</company_name>\n</account>","language":"xml"}]},"params":[{"_id":"557f4a527eafa719001d1c43","default":"","desc":"A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot character. Max of 50 characters","name":"account_code","required":true,"type":"string"},{"_id":"557f4a527eafa719001d1c42","default":"","desc":"The username for the account, ignore if you do not use usernames. Max of 255 characters","name":"username","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c41","default":"","desc":"The email address for the account","name":"email","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c40","default":"","desc":"The first name for the account. Max of 255 characters","name":"first_name","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c3f","default":"","desc":"The last name for the account. Max of 255 characters","name":"last_name","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c3e","default":"","desc":"The company name for the account. Max of 255 characters","name":"company_name","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c3d","default":"","desc":"The VAT number to avoid having the VAT applied (if applicable)","name":"vat_number","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c3c","default":"","desc":"The tax status for the account","name":"tax_exempt","required":false,"type":"boolean"},{"_id":"557f4a527eafa719001d1c3b","default":"","desc":"The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive","name":"entity_use_code","required":false,"type":"string"},{"_id":"557f4a527eafa719001d1c3a","default":"","desc":"The nested billing information. If present, the account will only be created after the billing information is validated","name":"billing_info","required":false,"type":"object"},{"_id":"557f4a527eafa719001d1c39","default":"","desc":"The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`","name":"address","required":false,"type":"object"},{"_id":"557f4a527eafa719001d1c38","default":"","desc":"The ISO 639-1 language code from the user's browser, indicating their preferred language and locale","name":"accept_language","required":false,"type":"string"}],"results":{"codes":[{"status":200,"language":"xml","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"></phone>\n  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-08-25T12:00:00Z</created_at>\n</account>","name":""}]},"settings":"","url":"/:account_code"},"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"You may optionally include billing information when updating an account. If the billing information is provided, the billing information will be validated. The account will only be updated if the billing information is valid.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T21:57:38.556Z","excerpt":"Updates an existing account.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"update-account","sync_unique":"","title":"Update Account","type":"put","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Account

Updates an existing account.

account_code:
required
String
A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z 0-9 @ - _ .] but it may not begin with a dot character. Max of 50 characters
username:
String
The username for the account, ignore if you do not use usernames. Max of 255 characters
email:
String
The email address for the account
first_name:
String
The first name for the account. Max of 255 characters
last_name:
String
The last name for the account. Max of 255 characters
company_name:
String
The company name for the account. Max of 255 characters
vat_number:
String
The VAT number to avoid having the VAT applied (if applicable)
tax_exempt:
Boolean
The tax status for the account
entity_use_code:
String
The Avalara AvaTax value that can be passed to identify the customer type for tax purposes. The range of values can be A - R (more info at Avalara). Value is case-sensitive
billing_info:
Object
The nested billing information. If present, the account will only be created after the billing information is validated
address:
Object
The nested address information for the account: `address1`, `address2`, `city`, `state`, `zip`, `country`, `phone`
accept_language:
String
The ISO 639-1 language code from the user's browser, indicating their preferred language and locale
[block:callout] { "type": "success", "title": "Please note", "body": "You may optionally include billing information when updating an account. If the billing information is provided, the billing information will be validated. The account will only be updated if the billing information is valid." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "success", "title": "Please note", "body": "You may optionally include billing information when updating an account. If the billing information is provided, the billing information will be validated. The account will only be updated if the billing information is valid." } [/block]
{"__v":0,"_id":"5595cb2bd4c23b0d00adf6fa","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $account = Recurly_Account::get('b6f5783');\n  $account->close();\n\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.destroy"},{"language":"python","code":"account = Account.get('1')\naccount.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.Close();"}]},"params":[{"_id":"55944ebb5c9eaa2300a86337","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"}],"results":{"codes":[{"status":204,"language":"xml","code":"Status: 204 No Content","name":""}]},"settings":"","url":"/accounts/:account_code"},"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"Closing an account permanently deletes its billing information and cancels any active subscriptions (canceled subscriptions will remain active until the end of the current billing cycle before expiring).\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T22:00:42.004Z","excerpt":"Marks an account as closed and cancels any active subscriptions.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"555fbba928249c1900618a82","slug":"close-account","sync_unique":"","title":"Close Account","type":"delete","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

deleteClose Account

Marks an account as closed and cancels any active subscriptions.

account_code:
required
String
Your unique account identifier.
[block:callout] { "type": "success", "title": "Please note", "body": "Closing an account permanently deletes its billing information and cancels any active subscriptions (canceled subscriptions will remain active until the end of the current billing cycle before expiring)." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "success", "title": "Please note", "body": "Closing an account permanently deletes its billing information and cancels any active subscriptions (canceled subscriptions will remain active until the end of the current billing cycle before expiring)." } [/block]
{"__v":0,"_id":"5595cb2bd4c23b0d00adf6fb","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $account = Recurly_Account::get('b6f5783');\n  $account->reopen();\n\n  // Or to fetch and reopen in one call\n  // $account = Recurly_Account::reopenAccount('b6f5783');\n\n  print \"Account: $account\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n} catch (Recurly_ValidationError $e) {\n  print \"Account already open: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find '1'\naccount.reopen"},{"language":"python","code":"account = Account.get('1')\naccount.reopen() "},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.Reopen();"}]},"params":[{"_id":"55944ed45c9eaa2300a86339","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"}],"results":{"codes":[{"status":200,"language":"xml","code":"<account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n  <adjustments href=\"https://your-subdomain.recurly.com/v2/accounts/1/adjustments\"/>\n  <billing_info href=\"https://your-subdomain.recurly.com/v2/accounts/1/billing_info\"/>\n  <invoices href=\"https://your-subdomain.recurly.com/v2/accounts/1/invoices\"/>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/subscriptions\"/>\n  <transactions href=\"https://your-subdomain.recurly.com/v2/accounts/1/transactions\"/>\n  <account_code>1</account_code>\n  <state>active</state>\n  <username nil=\"nil\"></username>\n  <email>verena@example.com</email>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company_name>New Company Name</company_name>\n  <vat_number nil=\"nil\"></vat_number>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <address>\n    <address1>123 Main St.</address1>\n    <address2 nil=\"nil\"></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone nil=\"nil\"></phone>\n  </address>\n  <accept_language nil=\"nil\"></accept_language>\n  <hosted_login_token>a92468579e9c4231a6c0031c4716c01d</hosted_login_token>\n  <created_at type=\"datetime\">2015-08-25T12:00:00Z</created_at>\n</account>","name":""}]},"settings":"","url":"/accounts/:account_code/reopen"},"body":"[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Please note\",\n  \"body\": \"Editing an account, creating an account with the same `account_code` as the deleted account, or creating a new transaction or subscription will also reopen an account. Reopening an account will restore its history. Reopening an account does not modify any previously canceled or expired subscriptions and billing information will need to be provided by the customer to continue billing.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T22:03:14.174Z","excerpt":"Transitions a closed account back to active.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"project":"555fbba928249c1900618a82","slug":"reopen-account","sync_unique":"","title":"Reopen Account","type":"put","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putReopen Account

Transitions a closed account back to active.

account_code:
required
String
Your unique account identifier.
[block:callout] { "type": "success", "title": "Please note", "body": "Editing an account, creating an account with the same `account_code` as the deleted account, or creating a new transaction or subscription will also reopen an account. Reopening an account will restore its history. Reopening an account does not modify any previously canceled or expired subscriptions and billing information will need to be provided by the customer to continue billing." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "success", "title": "Please note", "body": "Editing an account, creating an account with the same `account_code` as the deleted account, or creating a new transaction or subscription will also reopen an account. Reopening an account will restore its history. Reopening an account does not modify any previously canceled or expired subscriptions and billing information will need to be provided by the customer to continue billing." } [/block]
{"__v":0,"_id":"5595cb2bd4c23b0d00adf6fc","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $notes = Recurly_NoteList::get('b6f5783');\n  foreach ($notes as $note) {\n    print \"Note: {$note->message}\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","name":""},{"language":"python","code":"try:\n  account = Account.get('1')\n  for note in account.notes():\n   print \"Note: %s\" % note.message\nexcept NotFoundError:\n  print \"Account not found.\\n\""},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar notes = account.GetNotes();\nwhile (notes.Any())\n{\n\tforeach (var note in notes)\n\t\tConsole.WriteLine(\"Note: \" + note.Message);\n\tnotes = notes.Next;\n}"}]},"params":[{"_id":"55944eddccc3052300569882","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"}],"results":{"codes":[{"status":200,"language":"xml","code":"<notes type=\"array\">\n  <note>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <message>This is my second note</message>\n    <created_at type=\"datetime\">2015-08-14T18:53:04Z</created_at>\n  </note>\n  <note>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <message>This is my first note</message>\n    <created_at type=\"datetime\">2015-08-14T18:52:50Z</created_at>\n  </note>\n  <!-- Continued... -->\n</notes>","name":""}]},"settings":"","url":"/accounts/:account_code/notes"},"body":"","category":"5595cb2ad4c23b0d00adf6e7","createdAt":"2015-06-15T22:04:40.352Z","excerpt":"Returns a list of the notes on an account sorted in descending order.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"project":"555fbba928249c1900618a82","slug":"list-account-notes","sync_unique":"","title":"List Account Notes","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getList Account Notes

Returns a list of the notes on an account sorted in descending order.

account_code:
required
String
Your unique account identifier.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf6fd","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $adjustments = Recurly_AdjustmentList::get('b6f5783');\n  foreach ($adjustments as $adjustment) {\n    print \"Adjustment: $adjustment\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid account code: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.adjustments.find_each do |adjustment|\n  puts \"Adjustment: #{adjustment.inspect}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\naccount = Account.get('1')\nadjustments = account.adjustments()\nwhile adjustments:\n    for adjustment in adjustments:\n        print 'Adjustment: %s' % adjustment\n    try:\n        adjustments = adjustments.next_page()\n    except PageError:\n        adjustments = ()\n\n#client version 2.1.6+\naccount = Account.get('1')\nfor adjustment in account.adjustments():\n    print 'Adjustment: %s' % adjustment"},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar adjustments = account.GetAdjustments();\nwhile (adjustments.Any())\n{\n\tforeach (var adjustment in adjustments)\n\t\tConsole.WriteLine(\"Adjustment: \" + adjustment);\n\tadjustments = adjustments.Next;\n}"}]},"params":[{"_id":"55944ef00c33bd0d00059647","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"557f4ffce211d20d0060149f","required":false,"desc":"The type of adjustment to return: \"charge\" or \"credit\"","default":"all","type":"string","name":"type"},{"_id":"557f4ffce211d20d0060149e","required":false,"desc":"The state of the adjustments to return: \"pending\" or \"invoiced\".","default":"all","type":"string","name":"state"},{"_id":"557f4ffce211d20d0060149d","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"557f4ffce211d20d0060149c","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<adjustments type=\"array\">\n  <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/100\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>626db120a84102b1809909071c701c60</uuid>\n    <state>invoiced</state>\n    <description>One-time Charged Fee</description>\n    <accounting_code nil=\"nil\"/>\n    <product_code>basic</product_code>\n    <origin>debit</origin>\n    <unit_amount_in_cents type=\"integer\">2000</unit_amount_in_cents>\n    <quantity type=\"integer\">1</quantity>\n    <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid> <!-- Only shows if adjustment is a credit created from another credit. -->\n    <discount_in_cents type=\"integer\">0</discount_in_cents>\n    <tax_in_cents type=\"integer\">180</tax_in_cents>\n    <total_in_cents type=\"integer\">2180</total_in_cents>\n    <currency>USD</currency>\n    <taxable type=\"boolean\">false</taxable>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <tax_code nil=\"nil\"/>\n    <start_date type=\"datetime\">2011-08-31T03:30:00Z</start_date>\n    <end_date nil=\"nil\"/>\n    <created_at type=\"datetime\">2011-08-31T03:30:00Z</created_at>\n  </adjustment>\n  <!-- Continued... -->\n</adjustments>","name":""}]},"settings":"","url":"/accounts/:account_code/adjustments"},"body":"","category":"5595cb2ad4c23b0d00adf6e4","createdAt":"2015-06-15T22:21:48.674Z","excerpt":"Lists all charges and credits issued for a given account.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"list-an-accounts-adjustments","sync_unique":"","title":"List an Account's Adjustments","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getList an Account's Adjustments

Lists all charges and credits issued for a given account.

account_code:
required
String
Your unique account identifier.
type:
Stringall
The type of adjustment to return: "charge" or "credit"
state:
Stringall
The state of the adjustments to return: "pending" or "invoiced".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
Integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"5595cb2bd4c23b0d00adf6fe","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $adjustment = Recurly_Adjustment::get('2fded6a3e36e8b56b37007432f8c1b0d');\n  print \"Adjustment: $adjustment\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid adjustment uuid: $e\";\n}","name":""},{"language":"ruby","code":"adjustment = Recurly::Adjustment.find('30498bb2d52bb9037b4d62480eb98b8f')\n"},{"language":"python","code":"adjustment = Adjustment.get('30498bb2d52bb9037b4d62480eb98b8f')\n"},{"language":"csharp","code":"var adjustment = Adjustments.Get(\"30498bb2d52bb9037b4d62480eb98b8f\");\nConsole.WriteLine(\"Adjustment: \" + adjustment);"}]},"params":[{"_id":"55944f4fccc3052300569883","required":true,"desc":"The unique identifier for the adjustment","default":"","type":"string","name":"uuid"},{"_id":"557f50b0e211d20d006014a4","required":false,"desc":"The type of adjustment to return: \"charge\" or \"credit\"","default":"credits and charges","type":"string","name":"type"},{"_id":"557f50b0e211d20d006014a3","required":false,"desc":"The state of the adjustments to return: \"pending\" or \"invoiced\".","default":"active","type":"string","name":"state"},{"_id":"557f50b0e211d20d006014a2","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"}],"results":{"codes":[{"status":200,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/100\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <uuid>626db120a84102b1809909071c701c60</uuid>\n  <state>invoiced</state>\n  <description>One-time Charged Fee</description>\n  <accounting_code/>\n  <product_code>basic</product_code>\n  <origin>debit</origin>\n  <unit_amount_in_cents type=\"integer\">2000</unit_amount_in_cents>\n  <quantity type=\"integer\">1</quantity>\n  <original_adjustment_uuid>2cc95aa62517e56d5bec3a48afa1b3b9</original_adjustment_uuid> <!-- Only shows if adjustment is a credit created from another credit. -->\n  <discount_in_cents type=\"integer\">0</discount_in_cents>\n  <tax_in_cents type=\"integer\">175</tax_in_cents>\n  <total_in_cents type=\"integer\">2175</total_in_cents>\n  <currency>USD</currency>\n  <taxable type=\"boolean\">false</taxable>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_details type=\"array\">\n    <tax_detail>\n      <name>california</name>\n      <type>state</type>\n      <tax_rate type=\"float\">0.065</tax_rate>\n      <tax_in_cents type=\"integer\">130</tax_in_cents>\n    </tax_detail>\n    <tax_detail>\n      <name>san mateo county</name>\n      <type>county</type>\n      <tax_rate type=\"float\">0.01</tax_rate>\n      <tax_in_cents type=\"integer\">20</tax_in_cents>\n    </tax_detail>\n    <tax_detail>\n      <name>sf municipal tax</name>\n      <type>city</type>\n      <tax_rate type=\"float\">0.0</tax_rate>\n      <tax_in_cents type=\"integer\">0</tax_in_cents>\n    </tax_detail>\n    <tax_detail>\n      <name nil=\"nil\"/>\n      <type>special</type>\n      <tax_rate type=\"float\">0.0125</tax_rate>\n      <tax_in_cents type=\"integer\">25</tax_in_cents>\n    </tax_detail>\n  </tax_details>\n  <start_date type=\"datetime\">2015-02-04T23:13:07Z</start_date>\n  <end_date nil=\"nil\"/>}}}\n  <created_at type=\"datetime\">2015-02-04T23:13:07Z</created_at>\n</adjustment>","name":""}]},"settings":"","url":"/adjustments/:uuid"},"body":"","category":"5595cb2ad4c23b0d00adf6e4","createdAt":"2015-06-15T22:24:48.657Z","excerpt":"Returns information about a single adjustment.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"get-an-adjustment","sync_unique":"","title":"Get an Adjustment","type":"get","updates":["55b79c68aea7c8190058b98e"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getGet an Adjustment

Returns information about a single adjustment.

uuid:
required
String
The unique identifier for the adjustment
type:
Stringcredits and charges
The type of adjustment to return: "charge" or "credit"
state:
Stringactive
The state of the adjustments to return: "pending" or "invoiced".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2dd4c23b0d00adf749","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $charge = new Recurly_Adjustment();\n  $charge->account_code = 'b6f5783';\n  $charge->description = 'Charge for extra bandwidth';\n  $charge->unit_amount_in_cents = 5000; // $50.00\n  $charge->currency = 'USD';\n  $charge->quantity = 1;\n  $charge->accounting_code = 'bandwidth';\n  $charge->tax_exempt = false;\n  $charge->create();\n\n  print \"Charge: $charge\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.adjustments.create(\n  :description          => 'Charge for extra bandwidth',\n  :unit_amount_in_cents => 50_00,\n  :currency             => 'USD',\n  :quantity             => 1,\n  :accounting_code      => 'bandwidth'\n  :tax_exempt           => false\n)"},{"language":"python","code":"account = Account.get('1')\ncharge = Adjustment(\n  description='Charge for extra bandwidth',\n  unit_amount_in_cents=5000,\n  currency='USD',\n  quantity=1,\n  accounting_code='bandwidth'\n  tax_exempt=False\n)\naccount.charge(charge)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar adjustment = account.NewAdjustment(\n\t\"USD\",                        // currency\n\t5000,                         // unit_amount_in_cents\n\t\"Charge for extra bandwidth\", // description\n\t1,                            // quantity\n\t\"bandwidth\",                  // accounting_code\n\tfalse);                       // tax_exempt\nadjustment.Create();"},{"language":"xml","code":"<adjustment>\n  <description>Charge for extra bandwidth</description>\n  <unit_amount_in_cents>5000</unit_amount_in_cents>\n  <currency>USD</currency>\n  <quantity>1</quantity>\n  <accounting_code>bandwidth</accounting_code>\n  <tax_exempt>false</tax_exempt>\n</adjustment>"}]},"params":[{"_id":"557f5188eb75d80d00af40a7","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"557f5188eb75d80d00af40a6","required":true,"desc":"Currency, 3-letter ISO code","default":"","type":"string","name":"currency"},{"_id":"557f5188eb75d80d00af40a5","required":true,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":"","type":"string","name":"unit_amount_in_cents"},{"_id":"557f5188eb75d80d00af40a4","required":false,"desc":"Description of the adjustment for the invoice.","default":"","type":"string","name":"description"},{"_id":"557f5188eb75d80d00af40a3","default":"1","desc":"Quantity","name":"quantity","required":false,"type":"int"},{"_id":"557f5188eb75d80d00af40a2","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string","name":"accounting_code"},{"_id":"557f5188eb75d80d00af40a1","required":false,"desc":"`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.","default":"","type":"boolean","name":"tax_exempt"},{"_id":"557f5188eb75d80d00af40a0","required":false,"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.","default":"","type":"string","name":"tax_code"},{"_id":"55e09fbfa44fae0d0021473e","default":"Today","desc":"A timestamp associated with when the charge began","name":"start_date","required":false,"type":"timestamp"},{"_id":"55e09fbfa44fae0d0021473d","default":"","desc":"A timestamp associated with when the charge ended","name":"end_date","required":false,"type":"timestamp"}],"results":{"codes":[{"status":201,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <uuid>626db120a84102b1809909071c701c60</uuid>\n  <state>pending</state>\n  <description>Charge for extra bandwidth</description>\n  <accounting_code>bandwidth</accounting_code>\n  <product_code nil=\"nil\"/>\n  <origin>debit</origin>\n  <unit_amount_in_cents type=\"integer\">5000</unit_amount_in_cents>\n  <quantity type=\"integer\">1</quantity>\n  <discount_in_cents type=\"integer\">0</discount_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">5000</total_in_cents>\n  <currency>USD</currency>\n  <taxable type=\"boolean\">false</taxable>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <start_date type=\"datetime\">2015-02-04T23:54:06Z</start_date>\n  <end_date nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-02-04T23:54:06Z</created_at>\n</adjustment>","name":""}]},"settings":"","url":"/accounts/:account_code/adjustments"},"body":"","category":"5595cb2ad4c23b0d00adf6e4","createdAt":"2015-06-15T22:28:24.162Z","excerpt":"Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"create-a-charge-or-credit","sync_unique":"","title":"Create a Charge","type":"post","updates":["55b2f1b5a96deb1900990c6f"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate a Charge

Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.

account_code:
required
String
Your unique account identifier.
currency:
required
String
Currency, 3-letter ISO code
unit_amount_in_cents:
required
String
Positive amount for a charge, negative amount for a credit. Max 10000000.
description:
String
Description of the adjustment for the invoice.
quantity:
Integer1
Quantity
accounting_code:
String
Accounting code. Max of 20 characters.
tax_exempt:
Boolean
`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.
tax_code:
String
Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.
start_date:
TimestampToday
A timestamp associated with when the charge began
end_date:
Timestamp
A timestamp associated with when the charge ended

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"55c503d8a13abc25008c9048","api":{"auth":"required","examples":{"codes":[{"name":"","code":"$credit = new Recurly_Adjustment();\n$credit->account_code = '1';\n$credit->description = 'Refund for being a great customer';\n$credit->unit_amount_in_cents = -2000; // Negative $20.00.\n$credit->currency = 'USD';\n$credit->quantity = 1;\n$credit->create();","language":"php"},{"code":"account = Recurly::Account.find('1')\naccount.adjustments.create(\n  :description          => 'Refund for being a great customer',\n  :unit_amount_in_cents => -20_00,\n  :currency             => 'USD',\n  :quantity             => 1\n)","language":"ruby"},{"code":"account = Account.get('1')\ncredit = Adjustment(\n  description='Refund for being a great customer',\n  unit_amount_in_cents=-2000,\n  currency='USD',\n  quantity=1\n)\naccount.charge(credit)","language":"python"},{"code":"var account = Accounts.Get(\"1\");\nvar adjustment = account.CreateAdjustment(\n\t\"USD\",                               // currency\n\t-2000,                               // unit_amount_in_cents\n\t\"Refund for being a great customer\", // description\n\t1);                                  // quantity (default is 1)\nadjustment.Create();","language":"csharp"},{"code":"<adjustment>\n  <description>Refund for being a great customer</description>\n  <unit_amount_in_cents>-2000</unit_amount_in_cents>\n  <currency>USD</currency>\n  <quantity>1</quantity>\n</adjustment>","language":"xml"}]},"params":[{"_id":"557f5188eb75d80d00af40a7","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"557f5188eb75d80d00af40a6","required":true,"desc":"Currency, 3-letter ISO code","default":"","type":"string","name":"currency"},{"_id":"557f5188eb75d80d00af40a5","required":true,"desc":"Positive amount for a charge, negative amount for a credit. Max 10000000.","default":"","type":"string","name":"unit_amount_in_cents"},{"_id":"557f5188eb75d80d00af40a4","required":false,"desc":"Description of the adjustment for the invoice.","default":"","type":"string","name":"description"},{"_id":"557f5188eb75d80d00af40a3","required":false,"desc":"Quantity","default":"1","type":"string","name":"quantity"},{"_id":"557f5188eb75d80d00af40a2","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string","name":"accounting_code"},{"_id":"557f5188eb75d80d00af40a1","required":false,"desc":"`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.","default":"","type":"boolean","name":"tax_exempt"},{"_id":"557f5188eb75d80d00af40a0","required":false,"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.","default":"","type":"string","name":"tax_code"},{"_id":"55e0dcbda44fae0d0021491f","default":"Today","desc":"A timestamp associated with when the credit began","name":"start_date","required":false,"type":"timestamp"},{"_id":"55e0dcbda44fae0d0021491e","default":"","desc":"A timestamp associated with when the credit ended","name":"end_date","required":false,"type":"timestamp"}],"results":{"codes":[{"status":201,"language":"xml","code":"<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/945a4cb9afd64300b97b138407a51aef\" type=\"credit\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <uuid>945a4cb9afd64300b97b138407a51aef</uuid>\n  <state>pending</state>\n  <description>Refund for being a great customer</description>\n  <accounting_code nil=\"nil\"/>\n  <product_code nil=\"nil\"/>\n  <origin>credit</origin>\n  <unit_amount_in_cents type=\"integer\">-2000</unit_amount_in_cents>\n  <quantity type=\"integer\">1</quantity>\n  <discount_in_cents type=\"integer\">0</discount_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">-2000</total_in_cents>\n  <currency>USD</currency>\n  <taxable type=\"boolean\">false</taxable>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <start_date type=\"datetime\">2015-02-04T23:56:56Z</start_date>\n  <end_date nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-02-04T23:56:56Z</created_at>\n</adjustment>","name":""}]},"settings":"","url":"/accounts/:account_code/adjustments"},"body":"","category":"5595cb2ad4c23b0d00adf6e4","createdAt":"2015-08-07T19:15:36.088Z","excerpt":"Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-a-credit","sync_unique":"","title":"Create a Credit","type":"post","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate a Credit

Creates a one-time charge on an account. Charges are not invoiced or collected immediately. Non-invoiced charges will automatically be invoices when the account's subscription renews, or you trigger a collection by posting an invoice. Charges may be removed from an account if they have not been invoiced.

account_code:
required
String
Your unique account identifier.
currency:
required
String
Currency, 3-letter ISO code
unit_amount_in_cents:
required
String
Positive amount for a charge, negative amount for a credit. Max 10000000.
description:
String
Description of the adjustment for the invoice.
quantity:
String1
Quantity
accounting_code:
String
Accounting code. Max of 20 characters.
tax_exempt:
Boolean
`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings. This attribute does not work for credits (negative adjustments). Credits are always post-tax. Pre-tax discounts should use the Coupons feature.
tax_code:
String
Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.
start_date:
TimestampToday
A timestamp associated with when the credit began
end_date:
Timestamp
A timestamp associated with when the credit ended

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf6ff","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $adjustment = Recurly_Adjustment::get('626db120a84102b1809909071c701c60');\n  $adjustment->delete();\n\n  print \"Adjustment: $adjustment\";\n} catch (Recurly_NotFoundError $e) {\n  // NotFoundError if invalid uuid or already deleted\n  print \"Invalid adjustment uuid: $e\";\n}\n","name":""},{"language":"ruby","code":"adjustment = Recurly::Adjustment.find('945a4cb9afd64300b97b138407a51aef')\nadjustment.destroy"},{"language":"python","code":"adjustment = Adjustment.get('945a4cb9afd64300b97b138407a51aef')\nadjustment.delete()"},{"language":"text","code":"var adjustment = Adjustments.Get(\"945a4cb9afd64300b97b138407a51aef\");\nadjustment.Delete("}]},"params":[{"_id":"55944f6a0c33bd0d0005964a","required":true,"desc":"The unique identifier for the adjustment","default":"","type":"string","name":"uuid"}],"results":{"codes":[{"status":204,"language":"xml","code":"Status: 204 No Content"}]},"settings":"","url":"/adjustments/:uuid"},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Please note\",\n  \"body\": \"An adjustment may only be deleted if it has not been invoiced.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e4","createdAt":"2015-06-15T23:21:38.993Z","excerpt":"Delete a non-invoiced adjustment from an account.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"delete-an-adjustment","sync_unique":"","title":"Delete an Adjustment","type":"delete","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

deleteDelete an Adjustment

Delete a non-invoiced adjustment from an account.

uuid:
required
String
The unique identifier for the adjustment
[block:callout] { "type": "warning", "title": "Please note", "body": "An adjustment may only be deleted if it has not been invoiced." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "title": "Please note", "body": "An adjustment may only be deleted if it has not been invoiced." } [/block]
{"__v":0,"_id":"5595cb2cd4c23b0d00adf715","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = Recurly_BillingInfo::get('b6f5783');\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or account\n  // doesn't have billing info\n  print \"Not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nbilling_info = account.billing_info"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;"}]},"params":[{"_id":"55944f815c9eaa2300a8633a","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581ce0ea5474a0d00d946a1","required":false,"desc":"First name.","default":"","type":"string","name":"first_name"},{"_id":"5581ce0ea5474a0d00d946a0","required":false,"desc":"Last name.","default":"","type":"string","name":"last_name"},{"_id":"5581ce0ea5474a0d00d9469f","required":false,"desc":"Address line 1","default":"","type":"string","name":"address1"},{"_id":"5581ce0ea5474a0d00d9469e","required":false,"desc":"Address line 2","default":"","type":"string","name":"address2"},{"_id":"5581ce0ea5474a0d00d9469d","required":false,"desc":"City","default":"","type":"string","name":"city"},{"_id":"5581ce0ea5474a0d00d9469c","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581ce0ea5474a0d00d9469b","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements)","default":"","type":"string","name":"country"},{"_id":"5581ce0ea5474a0d00d9469a","required":false,"desc":"Zip or postal code","default":"","type":"string","name":"zip"},{"_id":"5581ce0ea5474a0d00d94699","required":false,"desc":"Customer's VAT number","default":"","type":"string","name":"vat_number"},{"_id":"5581ce0ea5474a0d00d94698","required":false,"desc":"Customer's IP address when updating their billing information","default":"","type":"string","name":"ip_address"},{"_id":"5581ce0ea5474a0d00d94697","required":false,"desc":"Country of IP address, if known by Recurly","default":"","type":"string","name":"ip_address_country"},{"_id":"5581ce0ea5474a0d00d94696","required":false,"desc":"Credit card number, first six digits","default":"","type":"int","name":"first_six"},{"_id":"5581ce0ea5474a0d00d94695","required":false,"desc":"Credit card number, last four digits","default":"","type":"int","name":"last_four"},{"_id":"5581ce0ea5474a0d00d94694","required":false,"desc":"Visa, MasterCard, American Express, Discover, JCB, etc","default":"","type":"string","name":"card_type"},{"_id":"5581ce0ea5474a0d00d94693","required":false,"desc":"Expiration month","default":"","type":"int","name":"month"},{"_id":"5581ce0ea5474a0d00d94692","required":false,"desc":"Expiration year","default":"","type":"int","name":"year"},{"_id":"5581ce0ea5474a0d00d94691","required":false,"desc":"PayPal Billing Agreement ID","default":"","type":"string","name":"paypal_billing_agreement_id"},{"_id":"5581ce0ea5474a0d00d94690","required":false,"desc":"Amazon Billing Agreement ID","default":"","type":"string","name":"amazon_billing_agreement_id"},{"_id":"5581ce0ea5474a0d00d9468f","required":false,"desc":"The name associated with the account. This may be a person's full name or a business name. name_on_account is used instead of first_name and last_name if the payment method is Bank Account.","default":"","type":"string","name":"name_on_account"},{"_id":"5581ce0ea5474a0d00d9468e","required":false,"desc":"U.S. bank account routing number","default":"","type":"int","name":"routing_number"},{"_id":"5581ce0ea5474a0d00d9468d","required":false,"desc":"Bank account number","default":"","type":"int","name":"account_number"},{"_id":"5581ce0ea5474a0d00d9468c","required":false,"desc":"Either 'checking' or 'savings'","default":"","type":"string","name":"account_type"}],"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone nil=\"nil\"></phone>\n  <vat_number>US1234567890</vat_number>\n  <ip_address>127.0.0.1</ip_address>\n  <ip_address_country>US</ip_address_country>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2015</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T19:44:14.605Z","excerpt":"Returns only the account's current billing information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"lookup-an-accounts-billing-info","sync_unique":"","title":"Lookup an Account's Billing Info","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getLookup an Account's Billing Info

Returns only the account's current billing information.

account_code:
required
String
Your unique account identifier.
first_name:
String
First name.
last_name:
String
Last name.
address1:
String
Address line 1
address2:
String
Address line 2
city:
String
City
state:
String
State
country:
String
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements)
zip:
String
Zip or postal code
vat_number:
String
Customer's VAT number
ip_address:
String
Customer's IP address when updating their billing information
ip_address_country:
String
Country of IP address, if known by Recurly
first_six:
Integer
Credit card number, first six digits
last_four:
Integer
Credit card number, last four digits
card_type:
String
Visa, MasterCard, American Express, Discover, JCB, etc
month:
Integer
Expiration month
year:
Integer
Expiration year
paypal_billing_agreement_id:
String
PayPal Billing Agreement ID
amazon_billing_agreement_id:
String
Amazon Billing Agreement ID
name_on_account:
String
The name associated with the account. This may be a person's full name or a business name. name_on_account is used instead of first_name and last_name if the payment method is Bank Account.
routing_number:
Integer
U.S. bank account routing number
account_number:
Integer
Bank account number
account_type:
String
Either 'checking' or 'savings'

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf716","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or token is invalid or expired\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  token_id: 'TOKEN_ID'\n}\naccount.billing_info.create"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.token_id = 'TOKEN_ID'\nbilling_info.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.TokenId = \"TOKEN_ID\";\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <token_id>TOKEN_ID</token_id>\n</billing_info>"}]},"params":[{"_id":"55944f99ccc3052300569885","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581ced4a5474a0d00d946a5","required":false,"desc":"A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token)","default":"","type":"string","name":"token_id"}],"results":{"codes":[{"status":201,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone nil=\"nil\"></phone>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2015</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T19:47:32.787Z","excerpt":"Creates an account's Billing Information using a [token generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's created Billing Information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"create-an-accounts-billing-info-token","sync_unique":"","title":"Create an Account's Billing Info (Token)","type":"post","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate an Account's Billing Info (Token)

Creates an account's Billing Information using a [token generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's created Billing Information.

account_code:
required
String
Your unique account identifier.
token_id:
String
A token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token)

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":3,"_id":"5595cb2cd4c23b0d00adf717","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->verification_value = '123';\n  $billing_info->month = 11;\n  $billing_info->year = 2017;\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or card are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :number             => '4111-1111-1111-1111',\n  :verification_value => '123',\n  :month              => 11,\n  :year               => 2015\n}\naccount.billing_info.create"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.verification_value = '123'\nbilling_info.month = 11\nbilling_info.year = 2015\nbilling_info.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.CreditCardNumber = \"4111-1111-1111-1111\";\ninfo.VerificationValue = \"123\";\ninfo.ExpirationMonth = 11;\ninfo.ExpirationYear = 2015;\ninfo.Create();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <number>4111-1111-1111-1111</number>\n  <verification_value>123</verification_value>\n  <month>11</month>\n  <year>2015</year>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"params":[{"_id":"55944fab5c9eaa2300a8633c","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581d09a8625220d00429e4d","required":true,"desc":"First name","default":"","type":"string","name":"first_name"},{"_id":"5581d09a8625220d00429e4c","required":true,"desc":"Last name","default":"","type":"string","name":"last_name"},{"_id":"5581d09a8625220d00429e42","required":true,"desc":"Credit card number, spaces and dashes are accepted","default":"","type":"string","name":"number"},{"_id":"5581d09a8625220d00429e41","required":true,"desc":"Expiration month","default":"","type":"string","name":"month"},{"_id":"5581d09a8625220d00429e40","required":true,"desc":"Expiration year","default":"","type":"string","name":"year"},{"_id":"5581d09a8625220d00429e4b","required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1"},{"_id":"5581d09a8625220d00429e4a","required":false,"desc":"Address line 2.","default":"","type":"string","name":"address2"},{"_id":"5581d09a8625220d00429e49","required":false,"desc":"City","default":"","type":"string","name":"city"},{"_id":"5581d09a8625220d00429e48","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581d09a8625220d00429e47","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d09a8625220d00429e46","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip"},{"_id":"5581d09a8625220d00429e45","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"_id":"5581d09a8625220d00429e44","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"5581d09a8625220d00429e3f","required":false,"desc":"Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**","default":"","type":"string","name":"verification_value"},{"_id":"5581d09a8625220d00429e43","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"}],"results":{"codes":[{"status":201,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone nil=\"nil\"></phone>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2015</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\n\nIf you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request.\n\nThe required address fields will correspond to the **address requirements** configured for your site.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details.\",\n  \"title\": \"Please note\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\",\n  \"title\": \"Please note\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T19:55:06.712Z","excerpt":"Creates the account's Billing Information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"create-an-accounts-billing-info-credit-card","sync_unique":"","title":"Create an Account's Billing Info (Credit Card)","type":"post","updates":["55d336260168850d0073f054"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate an Account's Billing Info (Credit Card)

Creates the account's Billing Information.

account_code:
required
String
Your unique account identifier.
first_name:
required
String
First name
last_name:
required
String
Last name
number:
required
String
Credit card number, spaces and dashes are accepted
month:
required
String
Expiration month
year:
required
String
Expiration year
address1:
String
Address line 1, recommended for address validation
address2:
String
Address line 2.
city:
String
City
state:
String
State
country:
String
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
String
Zip or postal code, recommended for address validation
phone:
String
Phone number
vat_number:
String
Customer's VAT Number
verification_value:
String
Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**
ip_address:
String
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**
Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information. When Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. The required address fields will correspond to the **address requirements** configured for your site. [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details.", "title": "Please note" } [/block] [block:callout] { "type": "warning", "body": "This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.", "title": "Please note" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when creating Billing Information. When Billing Information is submitted, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. The required address fields will correspond to the **address requirements** configured for your site. [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details.", "title": "Please note" } [/block] [block:callout] { "type": "warning", "body": "This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.", "title": "Please note" } [/block]
{"__v":1,"_id":"5595cb2cd4c23b0d00adf718","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->name_on_account = 'Acme Inc.';\n  $billing_info->routing_number = '065400137';\n  $billing_info->account_number = '4444000000005555';\n  $billing_info->account_type = 'checking';\n  $billing_info->address1 = '123 Main St.';\n  $billing_info->city = 'San Francisco';\n  $billing_info->state ='CA';\n  $billing_info->country = 'US';\n  $billing_info->zip = '94105';\n  $billing_info->create();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or bank account are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Account Not Found: $e\";\n}","language":"php"},{"code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  name_on_account: 'Acme, Inc.',\n  routing_number: '065400137',\n  account_number: '4444000000005555',\n  address1: '123 Main St.',\n  city: 'San Francisco',\n  state: 'CA',\n  country: 'US',\n  zip: '94105'\n}\naccount.billing_info.create","language":"ruby"},{"code":"account = Account.get('1')\nbilling_info = recurly.BillingInfo(\n  name_on_account = 'Acme, Inc.',\n  routing_number = '065400137',\n  account_number = '4444000000005555',\n  account_type = 'checking',\n  address1 = '123 Main St.',\n  city = 'San Francisco',\n  state ='CA',\n  country = 'US',\n  zip = '94105'\n  )\naccount.update_billing_info(billing_info)","language":"python"},{"code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.NameOnAccount = \"Acme, Inc.\";\ninfo.RoutingNumber = \"065400137\";\ninfo.AccountNumber = \"4444000000005555\";\ninfo.AccountType = BillingInfo.BankAccountType.Checking;\ninfo.Address1 = \"123 Main St.\";\ninfo.City = \"San Francisco\";\ninfo.State = \"CA\";\ninfo.Country = \"US\";\ninfo.PostalCode = \"94105\";\ninfo.Create();","language":"csharp"},{"code":"<billing_info>\n  <name_on_account>Acme, Inc.</name_on_account>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <routing_number>065400137</routing_number>\n  <account_number>4444000000005555</account_number>\n  <account_type>checking</account_type>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>","language":"xml"}]},"params":[{"_id":"55944fbb0c33bd0d0005964b","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581d1f08625220d00429e6d","required":true,"desc":"The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -","default":"","type":"string","name":"name_on_account"},{"_id":"5581d1f08625220d00429e63","required":true,"desc":"Must be a real U.S. bank account routing number. All routing numbers are 9 digits.","default":"","type":"int","name":"routing_number"},{"_id":"5581d1f08625220d00429e62","required":true,"desc":"Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.","default":"","type":"int","name":"account_number"},{"_id":"5581d1f08625220d00429e61","required":true,"desc":"Either 'checking' or 'savings'","default":"","type":"string","name":"account_type"},{"_id":"5581d1f08625220d00429e6c","required":false,"desc":"Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address1"},{"_id":"5581d1f08625220d00429e6b","required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2"},{"_id":"5581d1f08625220d00429e6a","required":false,"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city"},{"_id":"5581d1f08625220d00429e69","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string","name":"state"},{"_id":"5581d1f08625220d00429e68","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d1f08625220d00429e67","required":false,"desc":"Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789).","default":"","type":"string","name":"zip"},{"_id":"5581d1f08625220d00429e66","required":false,"desc":"Phone number, this field can be 10 digits.","default":"","type":"string","name":"phone"},{"_id":"5581d1f08625220d00429e65","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"5581d1f08625220d00429e64","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"}],"results":{"codes":[{"status":201,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"bank_account\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <name_on_account>Acme, Inc.</name_on_account>\n  <first_name nil=\"nil\"></first_name>\n  <last_name nil=\"nil\"></last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone></phone>\n  <vat_number></vat_number>\n  <ip_address nil=\"nil\"></ip_address>\n  <ip_address_country nil=\"nil\"></ip_address_country>\n  <account_type>checking</account_type>\n  <last_four>5555</last_four>\n  <routing_number>065400137</routing_number>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when creating Billing Information.\n\nWhen Billing Information is submitted, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated.\n\nIf you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request.\n\nThe required address fields will correspond to the **address requirements** configured for your site.\nIf you need to set a back dated subscription authorziation date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the \"bank_account_authorized_at\" attribute.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Please note\",\n  \"body\": \"Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T20:00:48.689Z","excerpt":"Creates the account's Billing Information with Bank Account details. You will need to have the ACH feature on your site for this call to work.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-an-accounts-billing-info-bank-account","sync_unique":"","title":"Create an Account's Billing Info (Bank Account)","type":"post","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

postCreate an Account's Billing Info (Bank Account)

Creates the account's Billing Information with Bank Account details. You will need to have the ACH feature on your site for this call to work.

account_code:
required
String
Your unique account identifier.
name_on_account:
required
String
The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -
routing_number:
required
Integer
Must be a real U.S. bank account routing number. All routing numbers are 9 digits.
account_number:
required
Integer
Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.
account_type:
required
String
Either 'checking' or 'savings'
address1:
String
Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -
address2:
String
Address line 2, this field has a 50 character max and can include: letters digits space . # / , -
city:
String
City, this field has a 50 character max and can include: letters digits space . , -
state:
String
State, this field has a 2 character max and can be lowercase or uppercase.
country:
String
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**
zip:
String
Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789).
phone:
String
Phone number, this field can be 10 digits.
vat_number:
String
Customer's VAT Number
ip_address:
String
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**
Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when creating Billing Information. When Billing Information is submitted, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. The required address fields will correspond to the **address requirements** configured for your site. If you need to set a back dated subscription authorziation date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute. [block:callout] { "type": "warning", "title": "Please note", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when creating Billing Information. When Billing Information is submitted, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. The required address fields will correspond to the **address requirements** configured for your site. If you need to set a back dated subscription authorziation date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute. [block:callout] { "type": "warning", "title": "Please note", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details." } [/block]
{"__v":0,"_id":"5595cb2cd4c23b0d00adf719","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->token_id = '7z6furn4jvb9'; // From Recurly.js\n  $billing_info->update();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account or token is invalid or expired\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info.token_id = 'TOKEN_ID'\naccount.billing_info.save"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.token_id = 'TOKEN_ID'\nbilling_info.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = new BillingInfo(account);\ninfo.TokenId = \"TOKEN_ID\";\ninfo.Update();"},{"language":"xml","code":"<billing_info>\n  <token_id>TOKEN_ID</token_id>\n</billing_info>"}]},"params":[{"_id":"55944fca5c9eaa2300a8633e","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581d2f8a5474a0d00d946bc","required":true,"desc":"A token [generated by Recurly.js.](https://docs.recurly.com/js/#getting-a-token)","default":"","type":"string","name":"token_id"}],"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone nil=\"nil\"></phone>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2015</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"[Recurly.js](https://js.recurly.com/) allows you to collect customer Billing Information and tokenize it, preventing your servers from having to handle credit card information. When you send these tokens to Recurly through our API, we unpack the token and update Billing Information accordingly.\n\nWhen Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\n\nIf you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include billing info with your request.","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T20:05:12.621Z","excerpt":"Updates an account's Billing Information using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's current Billing Information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"update-an-accounts-billing-info-token","sync_unique":"","title":"Update an Account's Billing Info (Token)","type":"put","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate an Account's Billing Info (Token)

Updates an account's Billing Information using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token). Returns the account's current Billing Information.

account_code:
required
String
Your unique account identifier.
token_id:
required
String
A token [generated by Recurly.js.](https://docs.recurly.com/js/#getting-a-token)
[Recurly.js](https://js.recurly.com/) allows you to collect customer Billing Information and tokenize it, preventing your servers from having to handle credit card information. When you send these tokens to Recurly through our API, we unpack the token and update Billing Information accordingly. When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include billing info with your request.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[Recurly.js](https://js.recurly.com/) allows you to collect customer Billing Information and tokenize it, preventing your servers from having to handle credit card information. When you send these tokens to Recurly through our API, we unpack the token and update Billing Information accordingly. When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include billing info with your request.
{"__v":2,"_id":"5595cb2cd4c23b0d00adf71a","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->first_name = 'Verena';\n  $billing_info->last_name = 'Example';\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->verification_value = '123';\n  $billing_info->month = 11;\n  $billing_info->year = 2017;\n  $billing_info->update();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or card are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  :first_name         => 'Verena',\n  :last_name          => 'Example',\n  :number             => '4111-1111-1111-1111',\n  :verification_value => '123',\n  :month              => 11,\n  :year               => 2015\n}\naccount.billing_info.save"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.first_name = 'Verena'\nbilling_info.last_name = 'Example'\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.verification_value = '123'\nbilling_info.month = 11\nbilling_info.year = 2015\nbilling_info.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;\ninfo.FirstName = \"Verana\";\ninfo.LastName = \"Example\";\ninfo.CreditCardNumber = \"4111-111-1111-1111\";\ninfo.VerificationValue = \"123\";\ninfo.ExpirationMonth = 11;\ninfo.ExpirationYear = 2015;\ninfo.Update();"},{"language":"xml","code":"<billing_info>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <number>4111-1111-1111-1111</number>\n  <verification_value>123</verification_value>\n  <month>11</month>\n  <year>2015</year>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"params":[{"_id":"55944fdb5c9eaa2300a8633f","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581d46f8625220d00429e81","required":false,"desc":"First name","default":"","type":"string","name":"first_name"},{"_id":"5581d46f8625220d00429e80","required":false,"desc":"Last name","default":"","type":"string","name":"last_name"},{"_id":"5581d46f8625220d00429e7f","required":false,"desc":"Address line 1, recommended for address validation","default":"","type":"string","name":"address1"},{"_id":"5581d46f8625220d00429e7e","required":false,"desc":"Address line 2","default":"","type":"string","name":"address2"},{"_id":"5581d46f8625220d00429e7d","required":false,"desc":"City","default":"","type":"string","name":"city"},{"_id":"5581d46f8625220d00429e7c","required":false,"desc":"State","default":"","type":"string","name":"state"},{"_id":"5581d46f8625220d00429e7b","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581d46f8625220d00429e7a","required":false,"desc":"Zip or postal code, recommended for address validation","default":"","type":"string","name":"zip"},{"_id":"5581d46f8625220d00429e79","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"_id":"5581d46f8625220d00429e78","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"5581d46f8625220d00429e76","required":false,"desc":"Credit card number, spaces and dashes are accepted","default":"","type":"string","name":"number"},{"_id":"5581d46f8625220d00429e75","required":false,"desc":"Expiration month","default":"","type":"string","name":"month"},{"_id":"5581d46f8625220d00429e74","required":false,"desc":"Expiration year","default":"","type":"string","name":"year"},{"_id":"5581d46f8625220d00429e73","required":false,"desc":"Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**","default":"","type":"string","name":"verification_value"},{"_id":"5581d46f8625220d00429e77","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"}],"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"credit_card\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone nil=\"nil\"></phone>\n  <card_type>Visa</card_type>\n  <year type=\"integer\">2015</year>\n  <month type=\"integer\">11</month>\n  <first_six>411111</first_six>\n  <last_four>1111</last_four>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when updating Billing Information. Non PCI sensitive billing info can be updated by api without re-submitting the token. This can be done in two ways: 1)Through the billing info api (docs. link: https://docs.recurly.com/api/billing-info#update-billing-info-credit-card ) whereby you submit only the information that needs to be updated. In that way, all other information remains unchanged on the account. 2) Providing the end user a unique url link to their billing info page, where they can update their own billing info securly. This link can be found in the configuration window of the subscriber's account. https://SUBDOMAIN.recurly.com/accounts/:account_code/edit. You will see a hosted billing information URL that takes the user to their billing site hosted by Recurly.\n\nWhen Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information.\n\nIf you want to create an account at the same time, you should use the [Account API](https://docs.recurly.com/api/accounts#create-account) end-point instead and include Billing Information with your request.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Please note\",\n  \"body\": \"This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details. You can, however, use this API call to update the billing address associated with an account.\",\n  \"title\": \"Please note\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T20:11:27.639Z","excerpt":"Returns the account's updated Billing Information.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"555fbba928249c1900618a82","slug":"update-an-accounts-billing-info-credit-card","sync_unique":"","title":"Update an Account's Billing Info (Credit Card)","type":"put","updates":["55d337a4f77e6d0d00b1afab"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate an Account's Billing Info (Credit Card)

Returns the account's updated Billing Information.

account_code:
required
String
Your unique account identifier.
first_name:
String
First name
last_name:
String
Last name
address1:
String
Address line 1, recommended for address validation
address2:
String
Address line 2
city:
String
City
state:
String
State
country:
String
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements) **STRONGLY RECOMMENDED**
zip:
String
Zip or postal code, recommended for address validation
phone:
String
Phone number
vat_number:
String
Customer's VAT Number
number:
String
Credit card number, spaces and dashes are accepted
month:
String
Expiration month
year:
String
Expiration year
verification_value:
String
Security code or CVV, 3-4 digits **STRONGLY RECOMMENDED**
ip_address:
String
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**
Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when updating Billing Information. Non PCI sensitive billing info can be updated by api without re-submitting the token. This can be done in two ways: 1)Through the billing info api (docs. link: https://docs.recurly.com/api/billing-info#update-billing-info-credit-card ) whereby you submit only the information that needs to be updated. In that way, all other information remains unchanged on the account. 2) Providing the end user a unique url link to their billing info page, where they can update their own billing info securly. This link can be found in the configuration window of the subscriber's account. https://SUBDOMAIN.recurly.com/accounts/:account_code/edit. You will see a hosted billing information URL that takes the user to their billing site hosted by Recurly. When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API](https://docs.recurly.com/api/accounts#create-account) end-point instead and include Billing Information with your request. [block:callout] { "type": "warning", "title": "Please note", "body": "This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information." } [/block] [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details. You can, however, use this API call to update the billing address associated with an account.", "title": "Please note" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Instead of using a token generated by Recurly.js, you can instead submit full credit card and address information when updating Billing Information. Non PCI sensitive billing info can be updated by api without re-submitting the token. This can be done in two ways: 1)Through the billing info api (docs. link: https://docs.recurly.com/api/billing-info#update-billing-info-credit-card ) whereby you submit only the information that needs to be updated. In that way, all other information remains unchanged on the account. 2) Providing the end user a unique url link to their billing info page, where they can update their own billing info securly. This link can be found in the configuration window of the subscriber's account. https://SUBDOMAIN.recurly.com/accounts/:account_code/edit. You will see a hosted billing information URL that takes the user to their billing site hosted by Recurly. When Billing Information is updated, it is only saved if valid. If the account has a past due invoice, the outstanding balance will be collected to validate the Billing Information. If you want to create an account at the same time, you should use the [Account API](https://docs.recurly.com/api/accounts#create-account) end-point instead and include Billing Information with your request. [block:callout] { "type": "warning", "title": "Please note", "body": "This API end-point may be used to import Billing Information without security codes (CVV). Recurly recommends requiring CVV from your customers when collecting new or updated Billing Information." } [/block] [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's credit card details. You can, however, use this API call to update the billing address associated with an account.", "title": "Please note" } [/block]
{"__v":3,"_id":"5595cb2cd4c23b0d00adf71b","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->account_code = 'b6f5783';\n  $billing_info->name_on_account = 'Acme Inc.';\n  $billing_info->routing_number = '065400137';\n  $billing_info->account_number = '4444000000005555';\n  $billing_info->account_type = 'checking';\n  $billing_info->address1 = '123 Main St.';\n  $billing_info->city = 'San Francisco';\n  $billing_info->state ='CA';\n  $billing_info->country = 'US';\n  $billing_info->zip = '94105';\n  $billing_info->update();\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_ValidationError $e) {\n  // The data or bank account are invalid\n  print \"Invalid data or card: $e\";\n} catch (Recurly_NotFoundError $e) {\n  // Could not find account\n  print \"Account Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.billing_info = {\n  name_on_account: 'Acme, Inc.',\n  routing_number: '065400137',\n  account_number: '4444000000005555',\n  address1: '123 Main St.',\n  city: 'San Francisco',\n  state: 'CA',\n  country: 'US',\n  zip: '94105'\n}\naccount.billing_info.save"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nbilling_info.name_on_account = 'Acme, Inc.'\nbilling_info.routing_number = '065400137'\nbilling_info.account_number = '4444000000005555'\nbilling_info.account_type = 'checking'\nbilling_info.address1 = '123 Main St.'\nbilling_info.city = 'San Francisco'\nbilling_info.state ='CA'\nbilling_info.country = 'US'\nbilling_info.zip = '94105'\nbilling_info.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar info = account.BillingInfo;\ninfo.NameOnAccount = \"Acme, Inc.\";\ninfo.RoutingNumber = \"065400137\";\ninfo.AccountNumber = \"4444000000005555\";\ninfo.AccountType = BillingInfo.BankAccountType.Checking;\ninfo.Address1 = \"123 Main St.\";\ninfo.City = \"San Francisco\";\ninfo.State = \"CA\";\ninfo.Country = \"US\";\ninfo.PostalCode = \"94105\";\ninfo.Update();"},{"language":"xml","code":"<billing_info>\n  <name_on_account>Acme, Inc.</name_on_account>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <routing_number>065400137</routing_number>\n  <account_number>4444000000005555</account_number>\n  <account_type>checking</account_type>\n  <ip_address>127.0.0.1</ip_address>\n</billing_info>"}]},"params":[{"_id":"55944ff05c9eaa2300a86341","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"},{"_id":"5581dafd8625220d00429ea7","required":true,"desc":"The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -","default":"","type":"string","name":"name_on_account"},{"_id":"5581dafd8625220d00429e9d","required":true,"desc":"Must be a real U.S. bank account routing number. All routing numbers are 9 digits.","default":"","type":"int","name":"routing_number"},{"_id":"5581dafd8625220d00429e9c","required":true,"desc":"Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.","default":"","type":"int","name":"account_number"},{"_id":"5581dafd8625220d00429e9b","required":true,"desc":"Either 'checking' or 'savings'","default":"","type":"int","name":"account_type"},{"_id":"5581dafd8625220d00429ea6","required":false,"desc":"Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address1"},{"_id":"5581dafd8625220d00429ea5","required":false,"desc":"Address line 2, this field has a 50 character max and can include: letters digits space . # / , -","default":"","type":"string","name":"address2"},{"_id":"5581dafd8625220d00429ea4","required":false,"desc":"City, this field has a 50 character max and can include: letters digits space . , -","default":"","type":"string","name":"city"},{"_id":"5581dafd8625220d00429ea3","required":false,"desc":"State, this field has a 2 character max and can be lowercase or uppercase.","default":"","type":"string","name":"state"},{"_id":"5581dafd8625220d00429ea2","required":false,"desc":"Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**","default":"","type":"string","name":"country"},{"_id":"5581dafd8625220d00429ea1","required":false,"desc":"Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789).","default":"","type":"string","name":"zip"},{"_id":"5581dafd8625220d00429ea0","required":false,"desc":"Phone number, this field can be 10 digits.","default":"","type":"string","name":"phone"},{"_id":"5581dafd8625220d00429e9f","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"5581dafd8625220d00429e9e","required":false,"desc":"Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**","default":"","type":"string","name":"ip_address"}],"results":{"codes":[{"status":200,"language":"xml","code":"<billing_info href=\"http://api.test.host/v2/accounts/1/billing_info\" type=\"bank_account\">\n  <account href=\"http://api.test.host/v2/accounts/1\"/>\n  <name_on_account>Acme, Inc.</name_on_account>\n  <first_name nil=\"nil\"></first_name>\n  <last_name nil=\"nil\"></last_name>\n  <company nil=\"nil\"></company>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"></address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone></phone>\n  <vat_number></vat_number>\n  <ip_address nil=\"nil\"></ip_address>\n  <ip_address_country nil=\"nil\"></ip_address_country>\n  <account_type>checking</account_type>\n  <last_four>5555</last_four>\n  <routing_number>065400137</routing_number>\n</billing_info>","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when updating Billing Information.\n\nWhen Billing Information is updated, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated.\n\nIf you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request.\n\nIf you need to set a back dated subscription authorization date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the \"bank_account_authorized_at\" attribute.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details. You can, however, use this API call to update the billing address associated with an account.\",\n  \"title\": \"Please note\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T20:39:25.270Z","excerpt":"Returns the account's updated Billing Information. You will need to have the ACH feature on your site for this call to work.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"project":"555fbba928249c1900618a82","slug":"update-an-accounts-billing-info-bank-account","sync_unique":"","title":"Update an Account's Billing Info (Bank Account)","type":"put","updates":["55d336d80168850d0073f056","55d33926f77e6d0d00b1afb5"],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate an Account's Billing Info (Bank Account)

Returns the account's updated Billing Information. You will need to have the ACH feature on your site for this call to work.

account_code:
required
String
Your unique account identifier.
name_on_account:
required
String
The name associated with the account. This may be a person's full name or a business name. This field must be 1 to 50 characters and can include: letters digits space . ' & , -
routing_number:
required
Integer
Must be a real U.S. bank account routing number. All routing numbers are 9 digits.
account_number:
required
Integer
Bank account number between 4 and 17 digits. We do not validate this number until the first transaction, so we recommend you have the customer confirm their account number.
account_type:
required
Integer
Either 'checking' or 'savings'
address1:
String
Address line 1, recommended for address validation. This field has a 50 character max and can include: letters digits space . # / , -
address2:
String
Address line 2, this field has a 50 character max and can include: letters digits space . # / , -
city:
String
City, this field has a 50 character max and can include: letters digits space . , -
state:
String
State, this field has a 2 character max and can be lowercase or uppercase.
country:
String
Country, [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements). **STRONGLY RECOMMENDED**
zip:
String
Zip or postal code, recommended for address validation. This field can be just 5 digits or can have an optional additional 4 digits separated by a hyphen (e.g. 12345-6789).
phone:
String
Phone number, this field can be 10 digits.
vat_number:
String
Customer's VAT Number
ip_address:
String
Customer's IP address when updating their Billing Information **STRONGLY RECOMMENDED**
Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when updating Billing Information. When Billing Information is updated, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. If you need to set a back dated subscription authorization date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute. [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details. You can, however, use this API call to update the billing address associated with an account.", "title": "Please note" } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Instead of using a token generated by Recurly.js, you can instead submit full bank account and address information when updating Billing Information. When Billing Information is updated, it is only saved if the required fields are provided and they meet the field validation requirements. If the account has a past due invoice, the outstanding balance will be collected when the Billing Information is updated. If you want to create an account at the same time, you should use the [Account API end-point](https://docs.recurly.com/api/accounts#create-account) instead and include Billing Information with your request. If you need to set a back dated subscription authorization date for the NACHA three year re-authorization rule, do so on the Create Subscription call using the "bank_account_authorized_at" attribute. [block:callout] { "type": "warning", "body": "Recurly strongly recommends using a token [generated by Recurly.js](https://docs.recurly.com/js/#getting-a-token) rather than directly handling your customer's bank account details. You can, however, use this API call to update the billing address associated with an account.", "title": "Please note" } [/block]
{"__v":0,"_id":"5595cb2cd4c23b0d00adf71c","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $billing_info = Recurly_BillingInfo::get('b6f5783');\n  $billing_info->delete();\n\n  // Or, in a single API request:\n  // Recurly_BillingInfo::deleteForAccount('b6f5783');\n\n  print \"Billing Info: $billing_info\";\n} catch (Recurly_NotFoundError $e) {\n  // Account not found or account does not have billing info\n  print \"Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nif billing_info = account.billing_info\n  billing_info.destroy\nend"},{"language":"python","code":"account = Account.get('1')\nbilling_info = account.billing_info\nif billing_info\n  billing_info.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.DeleteBillingInfo();"}]},"params":[{"_id":"55944ffb0c33bd0d0005964c","required":true,"desc":"Your unique account identifier.","default":"","type":"string","name":"account_code"}],"results":{"codes":[{"status":204,"language":"json","code":"Status: 204 No Content","name":""}]},"settings":"","url":"/accounts/:account_code/billing_info"},"body":"","category":"5595cb2ad4c23b0d00adf6e8","createdAt":"2015-06-17T20:40:02.831Z","excerpt":"You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"project":"555fbba928249c1900618a82","slug":"clear-an-accounts-billing-info","sync_unique":"","title":"Clear an Account's Billing Info","type":"delete","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

deleteClear an Account's Billing Info

You may remove any stored billing information for an account. If the account has a subscription, the renewal will go into past due unless you update the billing info before the renewal occurs.

account_code:
required
String
Your unique account identifier.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf72e","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$coupons = Recurly_CouponList::get();\nforeach ($coupons as $coupon) {\n  print \"Coupon: $coupon\\n\";\n}","name":""},{"language":"ruby","code":"Recurly::Coupon.find_each do |coupon|\n  puts \"Coupon: #{coupon.inspect}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\ncoupons = Coupon.all()\nwhile coupons:\n    for coupon in coupons:\n        print 'Coupon: %s' % coupon\n    try:\n        coupons = coupons.next_page()\n    except PageError:\n        coupons = ()\n\n#client version 2.1.6+\nfor coupon in Coupon.all():\n    print 'Coupon: %s' % coupon"},{"language":"csharp","code":"using System.Linq;\n\nvar coupons = Coupons.List();\nwhile (coupons.Any())\n{\n\tforeach (var coupon in coupons)\n\t\tConsole.WriteLine(\"Coupon: \" + coupon);\n\tcoupons = coupons.Next;\n}"}]},"params":[{"_id":"5581f3c38625220d00429ee7","required":false,"desc":"The state of coupons to return: \"redeemable\", \"expired\", \"maxed_out\", or \"inactive\".","default":"all","type":"string","name":"state"},{"_id":"5581f3c38625220d00429ee6","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"5581f3c38625220d00429ee5","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<coupons type=\"array\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n    <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n    <coupon_code>special</coupon_code>\n    <name>Special 10% off</name>\n    <state>redeemable</state>\n    <discount_type>percent</discount_type>\n    <discount_percent type=\"integer\">10</discount_percent>\n    <redeem_by_date type=\"datetime\">2014-01-01T07:00:00Z</redeem_by_date>\n    <single_use type=\"boolean\">false</single_use>\n    <applies_for_months nil=\"nil\"></applies_for_months>\n    <max_redemptions type=\"integer\">10</max_redemptions>\n    <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n    <created_at type=\"datetime\">2011-04-10T07:00:00Z</created_at>\n    <duration>temporal</duration>\n    <temporal_unit>day</temporal_unit>\n    <temporal_amount type=\"integer\">28</temporal_amount>\n    <plan_codes type=\"array\">\n      <plan_code>gold</plan_code>\n      <plan_code>platinum</plan_code>\n    </plan_codes>\n    <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n  </coupon>\n  <!-- Continued... -->\n</coupons>","name":""}]},"settings":"","url":"/coupons"},"body":"","category":"5595cb2ad4c23b0d00adf6e9","createdAt":"2015-06-17T22:25:07.292Z","excerpt":"Returns a list of all the coupons.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-active-coupons","sync_unique":"","title":"List Active Coupons","type":"get","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

getList Active Coupons

Returns a list of all the coupons.

state:
Stringall
The state of coupons to return: "redeemable", "expired", "maxed_out", or "inactive".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
Integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf730","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\ntry {\n  $coupon = Recurly_Coupon::get('special');\n  print \"Coupon: $coupon\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon does not exist\";\n}\n?>","name":""},{"language":"ruby","code":"coupon = Recurly::Coupon.find('special')"},{"language":"python","code":"coupon = Coupon.get('special')"},{"language":"csharp","code":"var coupon = Coupons.Get(\"special\");"}]},"params":[{"_id":"5594501e0c33bd0d0005964d","required":true,"desc":"Unique code to identify and redeem the coupon","default":"","type":"string","name":"coupon_code"}],"results":{"codes":[{"name":"","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <hosted_description>10% off coupon</hosted_description>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <redeem_by_date type=\"datetime\">2014-01-01T07:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">false</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions type=\"integer\">10</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2011-04-10T07:00:00Z</created_at>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount type=\"integer\">28</temporal_amount>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>","language":"xml","status":200}]},"settings":"","url":"/coupons/:coupon_code"},"body":"","category":"5595cb2ad4c23b0d00adf6e9","createdAt":"2015-06-17T22:55:45.346Z","excerpt":"Returns information about an active coupon.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"lookup-a-coupon","sync_unique":"","title":"Lookup a Coupon","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup a Coupon

Returns information about an active coupon.

coupon_code:
required
String
Unique code to identify and redeem the coupon

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2cd4c23b0d00adf731","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $coupon = new Recurly_Coupon();\n  $coupon->coupon_code = 'gorby1';\n  $coupon->redeem_by_date = '2016-07-04';\n  $coupon->duration = 'single_use';\n\n  // $2 off...\n  $coupon->name = 'Special $2 off coupon';\n  $coupon->discount_type = 'dollars';\n  $coupon->discount_in_cents->addCurrency('USD',200); // $2.00 discount\n\n  // ...or 10% off.\n  $coupon->name = 'Special 10% off';\n  $coupon->discount_type = 'percent';\n  $coupon->discount_percent = 10;\n\n  // Limit to gold and platinum plans only.\n  $coupon->applies_to_all_plans = false;\n  $coupon->plan_codes = array('gold', 'platinum');\n\n  $coupon->create();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid data: $e\";\n}","language":"php"},{"code":"coupon = Recurly::Coupon.new(\n  :coupon_code    => 'special',\n  :redeem_by_date => Date.new(2014, 1, 1),\n  :duration     => 'single_use'\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = 2_00\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = false\ncoupon.plan_codes = %w(gold platinum)\n\ncoupon.save","language":"ruby"},{"code":"coupon = Coupon(\n  coupon_code='special',\n  redeem_by_date=datetime.date(2014, 1, 1),\n  duration='single_use'\n)\n\n# $2 off...\ncoupon.name = 'Special $2 off coupon'\ncoupon.discount_type = 'dollars'\ncoupon.discount_in_cents = Money(200)\n\n# ...or 10% off.\ncoupon.name = 'Special 10% off'\ncoupon.discount_type = 'percent'\ncoupon.discount_percent = 10\n\n# Limit to gold and platinum plans only.\ncoupon.applies_to_all_plans = False\ncoupon.plan_codes = ['gold', 'platinum']\n\ncoupon.save()","language":"python"},{"code":"// new Coupon(<code>, <name>, <discount>)\n\n// $2 off...\nvar coupon = new Coupon(\"special\",\n        \"Special $2 off coupon\", new Dictionary<string, int>() { { \"USD\", 200 } });\n\n// ... or 10% off...\nvar coupon = new Coupon(\"special\",\n        \"Special 10% off coupon\", 10);\n\ncoupon.RedeemByDate = new DateTime(2017, 1, 1);\ncoupon.SingleUse = true;\n\n// Limit to gold and platinum plans only.\ncoupon.AppliesToAllPlans = false;\ncoupon.Plans.Add(\"gold\");\ncoupon.Plans.Add(\"silver\");\n\n// Other properties\ncoupon.RedeemByDate = new DateTime(2014, 1, 1);\ncoupon.SingleUse = true;\n\ncoupon.Create();","language":"csharp"},{"code":"// Request for specific plans:\n<coupon>\n  <coupon_code>special</coupon_code>\n  <name>Special $2 off coupon</name>\n  <discount_type>dollars</discount_type>\n  <redeem_by_date>2014-01-01</redeem_by_date>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount>28</temporal_amount>\n  <max_redemptions>10</max_redemptions>\n  <applies_to_all_plans>true</applies_to_all_plans>\n  <discount_in_cents>\n    <USD>200</USD>\n  </discount_in_cents>\n</coupon>\n\n\n// Request for $2 coupon:\n<coupon>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <discount_type>percent</discount_type>\n  <discount_percent>10</discount_percent>\n  <redeem_by_date>2014-01-01</redeem_by_date>\n  <duration>single_use</duration>\n  <max_redemptions>10</max_redemptions>\n  <applies_to_all_plans>false</applies_to_all_plans>\n  <plan_codes>\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n</coupon>","language":"xml","name":"XML"}]},"params":[{"_id":"5581fc9c8625220d00429f13","required":true,"desc":"Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters","default":"","type":"string","name":"coupon_code"},{"_id":"5581fc9c8625220d00429f12","required":true,"desc":"Coupon name","default":"","type":"string","name":"name"},{"_id":"5581fc9c8625220d00429f0a","required":true,"desc":"\"percent\" or \"dollars\"","default":"","type":"string","name":"discount_type"},{"_id":"5581fc9c8625220d00429f09","required":false,"desc":"Discount percentage if discount_type is \"percent\"","default":"","type":"int","name":"discount_percent"},{"_id":"5581fc9c8625220d00429f08","required":false,"desc":"Mapping of discount amounts by currency if discount_type is \"dollars\". Max 10000000.","default":"","type":"int","name":"discount_in_cents"},{"_id":"5581fc9c8625220d00429f11","required":false,"desc":"Description of the coupon on the hosted payment pages","default":"","type":"string","name":"hosted_description"},{"_id":"5581fc9c8625220d00429f10","required":false,"desc":"Description of the coupon on the invoice","default":"","type":"string","name":"invoice_description"},{"_id":"5581fc9c8625220d00429f0f","default":"","desc":"Last date to redeem the coupon, defaults to no date","name":"redeem_by_date","required":false,"type":"datetime"},{"_id":"55babe051b0d663700781631","required":false,"desc":"\"forever\"(default), \"single_use\", or \"temporal\".  If \"single_use\", the coupon applies to the first invoice only.  If \"temporal\" the coupon will apply to invoices for the duration determined by the temporal_unit and temporal_amount attributes.","default":"forever","type":"string","name":"duration"},{"_id":"55babe051b0d663700781630","required":false,"desc":"\"day\", \"week\", \"month\", or \"year\".  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.","default":"","type":"string","name":"temporal_unit"},{"_id":"55babe051b0d66370078162f","required":false,"desc":"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.","default":"","type":"int","name":"temporal_amount"},{"_id":"5581fc9c8625220d00429f0c","required":false,"desc":"Maximum number of accounts that may use the coupon before it can no longer be redeemed","default":"","type":"int","name":"max_redemptions"},{"_id":"5581fc9c8625220d00429f0b","required":false,"desc":"The coupon is valid for all plans if true, defaults to true","default":"","type":"boolean","name":"applies_to_all_plans"},{"_id":"5581fc9c8625220d00429f07","required":false,"desc":"Array of plan_codes the coupon applies to, if applies_to_all_plans is false","default":"","type":"array_string","name":"plan_codes"},{"_id":"5581fc9c8625220d00429f0d","required":false,"desc":"DEPRECATED: Please use \"temporal_unit\" and \"temporal_amount\". Number of months after redemption that the coupon is valid, defaults to no date","default":"","type":"int","name":"applies_for_months"},{"_id":"5581fc9c8625220d00429f0e","required":false,"desc":"DEPRECATED: Please use \"duration\". If true, the coupon applies to the first invoice only.","default":"","type":"boolean","name":"single_use"}],"results":{"codes":[{"name":"","code":"<coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\">\n  <redemptions href=\"https://your-subdomain.recurly.com/v2/coupons/special/redemptions\"/>\n  <coupon_code>special</coupon_code>\n  <name>Special 10% off</name>\n  <state>redeemable</state>\n  <discount_type>percent</discount_type>\n  <discount_percent type=\"integer\">10</discount_percent>\n  <redeem_by_date type=\"datetime\">2014-01-01T07:00:00Z</redeem_by_date>\n  <single_use type=\"boolean\">false</single_use>\n  <applies_for_months nil=\"nil\"></applies_for_months>\n  <max_redemptions type=\"integer\">10</max_redemptions>\n  <applies_to_all_plans type=\"boolean\">false</applies_to_all_plans>\n  <created_at type=\"datetime\">2011-04-10T07:00:00Z</created_at>\n  <duration>temporal</duration>\n  <temporal_unit>day</temporal_unit>\n  <temporal_amount type=\"integer\">28</temporal_amount>\n  <plan_codes type=\"array\">\n    <plan_code>gold</plan_code>\n    <plan_code>platinum</plan_code>\n  </plan_codes>\n  <a name=\"redeem\" href=\"https://your-subdomain.recurly.com/v2/coupons/special/redeem\" method=\"post\"/>\n</coupon>","language":"xml","status":201}]},"settings":"","url":"/coupons"},"body":"**DISCOUNT IN DOLLARS**\nWhen specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:\n```\n<discount_type>dollars</discount_type>\n<discount_in_cents>\n  <USD>500</USD>\n  <EUR>400</EUR>\n  <GBP>300</GBP>\n</discount_in_cents>\n```\n**DISCOUNT IN PERCENTAGE**\nPercentage discounts only need to specify the discount percentage. For example:\n```\n<discount_type>percent</discount_type>\n<discount_percent>10</discount_percent>\n```\n**LIMITING TO SPECIFIC PLANS**\nIf a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:\n```\n<applies_to_all_plans>false</applies_to_all_plans>\n<plan_codes>\n  <plan_code>silver</plan_code>\n  <plan_code>gold</plan_code>\n</plan_codes>\n```","category":"5595cb2ad4c23b0d00adf6e9","createdAt":"2015-06-17T23:02:52.933Z","excerpt":"Creates a new coupon. Please note: coupons cannot be updated after being created.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-coupon","sync_unique":"","title":"Create Coupon","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postCreate Coupon

Creates a new coupon. Please note: coupons cannot be updated after being created.

coupon_code:
required
String
Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters
name:
required
String
Coupon name
discount_type:
required
String
"percent" or "dollars"
discount_percent:
Integer
Discount percentage if discount_type is "percent"
discount_in_cents:
Integer
Mapping of discount amounts by currency if discount_type is "dollars". Max 10000000.
hosted_description:
String
Description of the coupon on the hosted payment pages
invoice_description:
String
Description of the coupon on the invoice
redeem_by_date:
DateTime
Last date to redeem the coupon, defaults to no date
duration:
Stringforever
"forever"(default), "single_use", or "temporal". If "single_use", the coupon applies to the first invoice only. If "temporal" the coupon will apply to invoices for the duration determined by the temporal_unit and temporal_amount attributes.
temporal_unit:
String
"day", "week", "month", or "year". 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.
temporal_amount:
Integer
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.
max_redemptions:
Integer
Maximum number of accounts that may use the coupon before it can no longer be redeemed
applies_to_all_plans:
Boolean
The coupon is valid for all plans if true, defaults to true
plan_codes:
Array of Strings
Array of plan_codes the coupon applies to, if applies_to_all_plans is false
applies_for_months:
Integer
DEPRECATED: Please use "temporal_unit" and "temporal_amount". Number of months after redemption that the coupon is valid, defaults to no date
single_use:
Boolean
DEPRECATED: Please use "duration". If true, the coupon applies to the first invoice only.
**DISCOUNT IN DOLLARS** When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example: ``` <discount_type>dollars</discount_type> <discount_in_cents> <USD>500</USD> <EUR>400</EUR> <GBP>300</GBP> </discount_in_cents> ``` **DISCOUNT IN PERCENTAGE** Percentage discounts only need to specify the discount percentage. For example: ``` <discount_type>percent</discount_type> <discount_percent>10</discount_percent> ``` **LIMITING TO SPECIFIC PLANS** If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example: ``` <applies_to_all_plans>false</applies_to_all_plans> <plan_codes> <plan_code>silver</plan_code> <plan_code>gold</plan_code> </plan_codes> ```

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



**DISCOUNT IN DOLLARS** When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example: ``` <discount_type>dollars</discount_type> <discount_in_cents> <USD>500</USD> <EUR>400</EUR> <GBP>300</GBP> </discount_in_cents> ``` **DISCOUNT IN PERCENTAGE** Percentage discounts only need to specify the discount percentage. For example: ``` <discount_type>percent</discount_type> <discount_percent>10</discount_percent> ``` **LIMITING TO SPECIFIC PLANS** If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example: ``` <applies_to_all_plans>false</applies_to_all_plans> <plan_codes> <plan_code>silver</plan_code> <plan_code>gold</plan_code> </plan_codes> ```
{"__v":4,"_id":"5595cb2cd4c23b0d00adf732","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $coupon = Recurly_Coupon::get('special');\n  $coupon->delete();\n\n  print \"Coupon: $coupon\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Coupon not found: $e\";\n}","language":"php"},{"code":"coupon = Recurly::Coupon.find('special')\ncoupon.destroy","language":"ruby"},{"code":"coupon = Coupon.get('special')\ncoupon.delete()","language":"python"},{"code":"var coupon = Coupons.Get(\"special\");\ncoupon.Deactivate();","language":"csharp"}]},"params":[],"results":{"codes":[{"status":204,"language":"xml","code":"Status: 204 No Content"}]},"settings":"","url":"/coupons/:coupon_code"},"body":"","category":"5595cb2ad4c23b0d00adf6e9","createdAt":"2015-06-17T23:28:22.499Z","excerpt":"Deactivate the coupon so customers can no longer redeem the coupon.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"deactivate-coupon","sync_unique":"","title":"Deactivate Coupon","type":"delete","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

deleteDeactivate Coupon

Deactivate the coupon so customers can no longer redeem the coupon.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2dd4c23b0d00adf744","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $account = Recurly_Account::get('b6f5783');\n  if ($account->redemption) {\n    $redemption = $account->redemption->get();\n    print \"Redemption: $redemption\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nredemption = account.redemption"},{"language":"python","code":"account = Account.get('1')\nredemption = account.redemption()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemption = account.GetActiveRedemption();"}]},"params":[{"_id":"558206aba5474a0d00d94777","required":false,"desc":"True if the coupon is valid for one use only","default":"","type":"boolean","name":"single_use"},{"_id":"558206aba5474a0d00d94776","required":false,"desc":"Total amount saved by the coupon","default":"","type":"int","name":"total_discounted_in_cents"},{"_id":"558206aba5474a0d00d94775","required":false,"desc":"Currency of the redemption","default":"","type":"string","name":"currency"},{"_id":"558206aba5474a0d00d94774","required":false,"desc":"State of the redemption","default":"","type":"string","name":"state"},{"_id":"558206aba5474a0d00d94773","required":false,"desc":"Date the coupon was redeemed","default":"","type":"timestamp","name":"created_at"}],"results":{"codes":[{"status":200,"language":"xml","code":"<redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\"/>\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <single_use type=\"boolean\">false</single_use>\n  <total_discounted_in_cents type=\"integer\">0</total_discounted_in_cents>\n  <currency>USD</currency>\n  <state>active</state>\n  <created_at type=\"datetime\">2011-06-27T12:34:56Z</created_at>\n</redemption>","name":""}]},"settings":"","url":"/accounts/:account_code/redemption"},"body":"","category":"5595cb2ad4c23b0d00adf6ed","createdAt":"2015-06-17T23:45:47.017Z","excerpt":"Lookup information about the 'active' coupon redemption on an account","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"lookup-a-coupon-redemption-on-an-account","sync_unique":"","title":"Lookup a Coupon Redemption on an Account","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup a Coupon Redemption on an Account

Lookup information about the 'active' coupon redemption on an account

single_use:
Boolean
True if the coupon is valid for one use only
total_discounted_in_cents:
Integer
Total amount saved by the coupon
currency:
String
Currency of the redemption
state:
String
State of the redemption
created_at:
Timestamp
Date the coupon was redeemed

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2dd4c23b0d00adf746","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$invoice = Recurly_Invoice::get('1');\nif($invoice->redemption) {\n  $redemption = $invoice->redemption->get();\n}","name":""},{"language":"ruby","code":"invoice = Recurly::Invoice.find('1')\nredemption = invoice.redemption"},{"language":"python","code":"invoice = Invoice.get('1')\nredemption = invoice.redemption()"},{"language":"csharp","code":"var invoice = Invoices.Get(1);\nvar redemption = invoice.GetRedemption();"}]},"params":[{"_id":"5582080e8625220d00429f3d","required":false,"desc":"True if the coupon is valid for one use only","default":"","type":"boolean","name":"single_use"},{"_id":"5582080e8625220d00429f3c","required":false,"desc":"Total amount saved by the coupon","default":"","type":"int","name":"total_discounted_in_cents"},{"_id":"5582080e8625220d00429f3b","required":false,"desc":"Currency of the redemption","default":"","type":"string","name":"currency"},{"_id":"5582080e8625220d00429f3a","required":false,"desc":"State of the redemption","default":"","type":"string","name":"state"},{"_id":"5582080e8625220d00429f39","required":false,"desc":"Date the coupon was redeemed","default":"","type":"timestamp","name":"created_at"}],"results":{"codes":[{"status":200,"language":"xml","code":"<redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\"/>\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <single_use type=\"boolean\">false</single_use>\n  <total_discounted_in_cents type=\"integer\">0</total_discounted_in_cents>\n  <currency>USD</currency>\n  <state>inactive</state>\n  <created_at type=\"datetime\">2011-06-27T12:34:56Z</created_at>\n</redemption>","name":""}]},"settings":"","url":"/invoices/:invoice_number/redemption"},"body":"","category":"5595cb2ad4c23b0d00adf6ed","createdAt":"2015-06-17T23:51:42.344Z","excerpt":"Lookup information about a coupon redemption applied to an invoice","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"lookup-a-coupon-redemption-on-an-invoice","sync_unique":"","title":"Lookup a Coupon Redemption on an Invoice","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup a Coupon Redemption on an Invoice

Lookup information about a coupon redemption applied to an invoice

single_use:
Boolean
True if the coupon is valid for one use only
total_discounted_in_cents:
Integer
Total amount saved by the coupon
currency:
String
Currency of the redemption
state:
String
State of the redemption
created_at:
Timestamp
Date the coupon was redeemed

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2dd4c23b0d00adf743","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n$coupon = Recurly_Coupon::get('special');\n$redemption = $coupon->redeemCoupon('1', 'USD');\n?>","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\ncoupon = Recurly::Coupon.find('special')\nredemption = coupon.redeem(account)"},{"language":"python","code":"coupon = Coupon.get('special')\nredemption = Redemption(account_code='1', currency='USD')\n\n# new redemption object returned from this method will contain the updates\n# so we overwrite the redemption variable\nredemption = coupon.redeem(redemption)"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemption = account.RedeemCoupon(\"special\", \"USD\");"},{"language":"xml","code":"<redemption>\n  <account_code>1</account_code>\n  <currency>USD</currency>\n</redemption>"}]},"params":[{"_id":"55820401a5474a0d00d94750","required":false,"desc":"Account code to apply redemption","default":"","type":"int","name":"account_code"},{"_id":"55820401a5474a0d00d9474f","required":false,"desc":"Currency for the redemption","default":"","type":"string","name":"currency"}],"results":{"codes":[{"status":201,"language":"xml","code":"<redemption href=\"https://your-subdomain.recurly.com/v2/accounts/1/redemption\">\n  <coupon href=\"https://your-subdomain.recurly.com/v2/coupons/special\"/>\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <single_use type=\"boolean\">false</single_use>\n  <total_discounted_in_cents type=\"integer\">0</total_discounted_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-06-27T12:34:56Z</created_at>\n</redemption>","name":""}]},"settings":"","url":"/coupons/:coupon_code/redeem"},"body":"","category":"5595cb2ad4c23b0d00adf6ed","createdAt":"2015-06-17T23:34:25.304Z","excerpt":"Most coupons are redeemed during a new subscription. This endpoint allows you to redeem a coupon for a customer after their initial subscription, or in anticipation of a future subscription. When you redeem a coupon on an account, the coupon will be applied to the next subscription creation (new subscription), modification (e.g. upgrade or downgrade), or renewal.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"redeem-a-coupon-before-or-after-a-subscription","sync_unique":"","title":"Redeem a Coupon Before or After a Subscription","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postRedeem a Coupon Before or After a Subscription

Most coupons are redeemed during a new subscription. This endpoint allows you to redeem a coupon for a customer after their initial subscription, or in anticipation of a future subscription. When you redeem a coupon on an account, the coupon will be applied to the next subscription creation (new subscription), modification (e.g. upgrade or downgrade), or renewal.

account_code:
Integer
Account code to apply redemption
currency:
String
Currency for the redemption

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2dd4c23b0d00adf745","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\n$redemption = Recurly_CouponRedemption::get('account_code');\n$redemption->delete();\n?>","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\nredemption = account.redemption\nredemption.destroy"},{"language":"python","code":"account = Account.get('1')\nredemption = account.redemption()\nredemption.delete()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar redemption = account.GetActiveRedemption();\nredemption.Delete();"}]},"params":[],"results":{"codes":[{"code":"Status: 204 No Content","language":"xml","status":204}]},"settings":"","url":"/accounts/:account_code/redemption"},"body":"","category":"5595cb2ad4c23b0d00adf6ed","createdAt":"2015-06-17T23:48:14.667Z","excerpt":"Occasionally, you may want to remove a coupon from an account. Recurly will automatically remove coupons after they expire or are otherwise no longer valid for an account. If you want to remove a coupon from an account before it expires, you may use the examples below. Please note: the coupon will still count towards the \"maximum redemption total\" of a coupon.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"remove-a-coupon-from-an-account","sync_unique":"","title":"Remove a Coupon from an Account","type":"delete","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

deleteRemove a Coupon from an Account

Occasionally, you may want to remove a coupon from an account. Recurly will automatically remove coupons after they expire or are otherwise no longer valid for an account. If you want to remove a coupon from an account before it expires, you may use the examples below. Please note: the coupon will still count towards the "maximum redemption total" of a coupon.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"5595cb2cd4c23b0d00adf723","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$invoices = Recurly_InvoiceList::get();\nforeach ($invoices as $invoice) {\n  print \"Invoice: $invoice\\n\";\n}","name":""},{"code":"Recurly::Invoice.find_each do |invoice|\n  puts \"Invoice: #{invoice.inspect}\"\nend","language":"ruby"},{"code":"#client version <= 2.1.5\ninvoices = Invoice.all()\nwhile invoices:\n    for invoice in invoices:\n        print 'Invoice: %s' % invoice\n    try:\n        invoices = invoices.next_page()\n    except PageError:\n        invoices = ()\n# ...or...\npast_due = Invoice.all_past_due()\n\n#client version 2.1.6+\nfor invoice in Invoice.all():\n    print 'Invoice: %s' % invoice","language":"python"},{"code":"using System.Linq;\n\nvar invoices = Invoices.List();\nwhile (invoices.Any())\n{\n\tforeach (var invoice in invoices)\n\t\tConsole.WriteLine(\"Invoice: \" + invoice);\n\tinvoices = invoices.Next;\n}","language":"csharp"}]},"params":[{"_id":"5582f2ae81672a3900bb4fe3","required":false,"desc":"The state of invoices to return: \"open\", \"collected\", \"failed\", or \"past_due\".","default":"all","type":"string","name":"state"},{"_id":"5582f2ae81672a3900bb4fe2","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"int","name":"cursor"},{"_id":"5582f2ae81672a3900bb4fe1","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"name":"","code":"<invoices type=\"array\">\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1005\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <address>\n        <address1>400 Alabama St.</address1>\n        <address2></address2>\n        <city>San Francisco</city>\n        <state>CA</state>\n        <zip>94110</zip>\n        <country>US</country>\n        <phone></phone>\n    </address>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n    <state>open</state>\n    <invoice_number_prefix></invoice_number_prefix> <!-- Only populated for VAT Country Invoice Sequencing. Shows a country code. -->\n    <invoice_number type=\"integer\">1005</invoice_number>\n    <po_number nil=\"nil\"></po_number>\n    <vat_number nil=\"nil\"></vat_number>\n    <subtotal_in_cents type=\"integer\">1200</subtotal_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <total_in_cents type=\"integer\">1200</total_in_cents>\n    <currency>USD</currency>\n    <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n    <closed_at nil=\"nil\"></closed_at>\n    <tax_type>usst</tax_type>\n\t<tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\">\n        <!-- Detail. -->\n      </adjustment>\n    </line_items>\n    <transactions type=\"array\">\n    </transactions>\n  </invoice>\n  <!-- Continued... -->\n</invoices>","language":"xml","status":200}]},"settings":"","url":"/invoices"},"body":"**INVOICE STATES**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"State\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Open, pending collection\",\n    \"0-0\": \"`open`\",\n    \"null-0\": \"`\",\n    \"1-0\": \"`collected`\",\n    \"1-1\": \"Collection completed successfully\",\n    \"2-0\": \"`failed`\",\n    \"2-1\": \"Failed to collect\",\n    \"3-0\": \"`past_due`\",\n    \"3-1\": \"Initial collection failed, still attempting collection\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please note: an invoice will only be in one state.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T16:32:46.758Z","excerpt":"Returns a list of all invoices.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-invoices","sync_unique":"","title":"List Invoices","type":"get","updates":["55b1055eb2405537003cd938"],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getList Invoices

Returns a list of all invoices.

state:
Stringall
The state of invoices to return: "open", "collected", "failed", or "past_due".
cursor:
Integer
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
Integer50
Number of records to return per page, up to a maximum of 200.
**INVOICE STATES** [block:parameters] { "data": { "h-0": "State", "h-1": "Description", "0-1": "Open, pending collection", "0-0": "`open`", "null-0": "`", "1-0": "`collected`", "1-1": "Collection completed successfully", "2-0": "`failed`", "2-1": "Failed to collect", "3-0": "`past_due`", "3-1": "Initial collection failed, still attempting collection" }, "cols": 2, "rows": 4 } [/block] [block:callout] { "type": "warning", "body": "Please note: an invoice will only be in one state." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



**INVOICE STATES** [block:parameters] { "data": { "h-0": "State", "h-1": "Description", "0-1": "Open, pending collection", "0-0": "`open`", "null-0": "`", "1-0": "`collected`", "1-1": "Collection completed successfully", "2-0": "`failed`", "2-1": "Failed to collect", "3-0": "`past_due`", "3-1": "Initial collection failed, still attempting collection" }, "cols": 2, "rows": 4 } [/block] [block:callout] { "type": "warning", "body": "Please note: an invoice will only be in one state." } [/block]
{"__v":1,"_id":"5595cb2cd4c23b0d00adf724","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $invoices = Recurly_InvoiceList::getForAccount('b6f5783');\n  foreach ($invoices as $invoice) {\n    print \"Invoice: {$invoice}\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.invoices.find_each do |invoice|\n  puts \"Invoice: #{invoice.inspect}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\naccount = Account.get('1')\ninvoices = account.invoices()\nwhile invoices:\n    for invoice in invoices:\n        print 'Invoice: %s' % invoice\n    try:\n        invoices = invoices.next_page()\n    except PageError:\n        invoices = ()\n\n#client version 2.1.6+\naccount = Account.get('1')\nfor invoices in account.invoices():\n    print 'Invoice: %s' % invoice"},{"language":"csharp","code":"using System.Linq;\n\n// Get the list of invoices through the Account\nvar account = Accounts.Get(\"1\");\nvar invoices = account.GetInvoices();\n\n// OR directly through Invoices\nvar invoices = Invoices.List(\"1\"); // account code\n\nwhile (invoices.Any())\n{\n\tforeach (var invoice in invoices)\n\t\tConsole.WriteLine(\"Invoice: \" + invoice);\n\tinvoices = invoices.Next;\n}"}]},"params":[{"_id":"5582f72aea39a939002242f5","required":false,"desc":"The state of invoices to return: \"open\", \"collected\", \"failed\", or \"past_due\".","default":"all","type":"string","name":"state"},{"_id":"5582f72aea39a939002242f4","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"5582f72aea39a939002242f3","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<invoices type=\"array\">\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1005\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n    <state>open</state>\n    <invoice_number type=\"integer\">1005</invoice_number>\n    <po_number nil=\"nil\"></po_number>\n    <vat_number nil=\"nil\"></vat_number>\n    <subtotal_in_cents type=\"integer\">1200</subtotal_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <total_in_cents type=\"integer\">1200</total_in_cents>\n    <currency>USD</currency>\n    <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n    <closed_at nil=\"nil\"></closed_at>\n    <tax_type>usst</tax_type>\n\t<tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n    <line_items type=\"array\">\n      <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\"/>\n        <!-- Detail. -->\n      </adjustment>\n    </line_items>\n    <transactions type=\"array\">\n    </transactions>\n  </invoice>\n  <!-- Continued... -->\n</invoices>","name":""}]},"settings":"","url":"/accounts/:account_code/invoices"},"body":"","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T16:51:54.366Z","excerpt":"Returns a list of all the invoices.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"list-an-accounts-invoices","sync_unique":"","title":"List an Account's Invoices","type":"get","updates":["55b103aab3a7e037008ac0d7"],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getList an Account's Invoices

Returns a list of all the invoices.

state:
Stringall
The state of invoices to return: "open", "collected", "failed", or "past_due".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
Integer50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":4,"_id":"5595cb2cd4c23b0d00adf725","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $invoice = Recurly_Invoice::get('1001');\n  print \"Invoice: $invoice\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice not found: $e\";\n}","name":""},{"language":"ruby","code":"invoice = Recurly::Invoice.find('1005')"},{"language":"python","code":"invoice = Invoice.get('1005')"},{"language":"csharp","code":"var invoice = Invoices.Get(1005);"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1402\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <address>\n      <address1>400 Alabama St.</address1>\n      <address2></address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94110</zip>\n      <country>US</country>\n      <phone></phone>\n    </address>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>open</state>\n  <invoice_number_prefix></invoice_number_prefix> <!-- Only populated for VAT Country Invoice Sequencing. Shows a country code. -->\n  <invoice_number type=\"integer\">1402</invoice_number>\n  <po_number nil=\"nil\"></po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">9900</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">9900</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0</tax_rate>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\"/>\n      <!-- Detail. -->\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>","name":""}]},"settings":"","url":"/invoices/:invoice_number"},"body":"**PAYMENTS**\nRecurly returns an array of payments applied to an Invoice. At the moment, there is usually only one successful payment per invoice. The API only returns successful payments—it does not return failed payment attempts on an invoice nor does it return refunds on payments made to an invoice.","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T16:56:30.329Z","excerpt":"Lookup an invoice to retrieve detailed information about its line items and payments.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"lookup-invoice-details","sync_unique":"","title":"Lookup Invoice Details","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup Invoice Details

Lookup an invoice to retrieve detailed information about its line items and payments.

**PAYMENTS** Recurly returns an array of payments applied to an Invoice. At the moment, there is usually only one successful payment per invoice. The API only returns successful payments—it does not return failed payment attempts on an invoice nor does it return refunds on payments made to an invoice.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



**PAYMENTS** Recurly returns an array of payments applied to an Invoice. At the moment, there is usually only one successful payment per invoice. The API only returns successful payments—it does not return failed payment attempts on an invoice nor does it return refunds on payments made to an invoice.
{"__v":3,"_id":"5595cb2cd4c23b0d00adf726","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $pdf = Recurly_Invoice::getInvoicePdf('1005');\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice not found: $e\";\n}","name":""},{"language":"ruby","code":"begin\n  pdf = Recurly::Invoice.find(\n    'invoice_number', :format => 'pdf'\n  )\nrescue Recurly::Resource::NotFound => e\n  puts 'Invoice not found.'\nend"},{"language":"python","code":"with open('invoice.pdf', 'w') as invoice_file:\n    invoice_file.write(recurly.Invoice.pdf('invoice_number'))"},{"language":"csharp","code":"var invoice = Invoices.Get(1005);\nbyte[] pdf = invoice.GetPdf();"}]},"params":[{"_id":"55c8d2fb71d7580d0063a5f1","required":true,"desc":"Instructs the API to return the invoice as a PDF.","default":"","type":"string","name":"Accept"},{"_id":"55c8d2fb71d7580d0063a5f0","required":false,"desc":"An [ISO-639-1 abbreviation](http://www.loc.gov/standards/iso639-2/php/code_list.php) of a [language supported by Recurly](https://docs.recurly.com/hosted-payment-pages#internationalized_hosted_payment_pages) The language that the PDF will be translated into. If this header is not used, the PDF returned will be in English.","default":"English","type":"string","name":"Accept-Language"}],"results":{"codes":[{"language":"text","code":""}]},"settings":"","url":"/invoices/:invoice_number"},"body":"","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:02:18.864Z","excerpt":"To retrieve a PDF invoice, modify the headers to request the `Accept` as `application/pdf`.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"retrieve-a-pdf-invoice","sync_unique":"","title":"Retrieve a PDF Invoice","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getRetrieve a PDF Invoice

To retrieve a PDF invoice, modify the headers to request the `Accept` as `application/pdf`.

Accept:
required
String
Instructs the API to return the invoice as a PDF.
Accept-Language:
StringEnglish
An [ISO-639-1 abbreviation](http://www.loc.gov/standards/iso639-2/php/code_list.php) of a [language supported by Recurly](https://docs.recurly.com/hosted-payment-pages#internationalized_hosted_payment_pages) The language that the PDF will be translated into. If this header is not used, the PDF returned will be in English.

Definition

{{ api_url }}{{ page_api_url }}

Examples



{"__v":2,"_id":"5595cb2cd4c23b0d00adf727","api":{"auth":"required","examples":{"codes":[{"language":"ruby","code":"account = Recurly::Account.find('1')\ninvoice = account.build_invoice","name":""}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<invoice href=\"\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <address>\n    <address1>123 Main St</address1>\n    <address2></address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>12345</zip>\n    <country>US</country>\n    <phone></phone>\n  </address>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>open</state>\n  <invoice_number type=\"integer\">1005</invoice_number>\n  <po_number nil=\"nil\"></po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">1200</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">1200</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0</tax_rate>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\"/>\n      <!-- Detail. -->\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>","name":""}]},"settings":"","url":"/accounts/:account_code/invoices/preview"},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:07:20.716Z","excerpt":"Preview allows you to display the invoice details, including estimated tax, before you post it.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"555fbba928249c1900618a82","slug":"preview-an-invoice","sync_unique":"","title":"Preview an Invoice","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postPreview an Invoice

Preview allows you to display the invoice details, including estimated tax, before you post it.

[block:callout] { "type": "warning", "body": "This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "body": "This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`." } [/block]
{"__v":3,"_id":"5595cb2cd4c23b0d00adf728","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $invoice = Recurly_Invoice::invoicePendingCharges('b6f5783');\n\n  print \"Invoice: $invoice\";\n} catch (Recurly_ValidationError $e) {\n  print \"No Charges to invoice: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Account not found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\n\n# invoice! takes invoice attributes as an optional argument\ninvoice = account.invoice!(terms_and_conditions: 't and c', customer_notes: 'notes')"},{"language":"python","code":"account = Account.get('1')\n\n# invoice() takes invoice attributes as optional kwargs\ninvoice = account.invoice(terms_and_conditions=\"t and c\", customer_notes=\"notes\")"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar invoice = account.InvoicePendingCharges();"}]},"params":[{"_id":"55c8c16d229b981900ed5fd6","required":false,"desc":"Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"55c8c16d229b981900ed5fd5","required":false,"desc":"Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"customer_notes"},{"_id":"55c8c16d229b981900ed5fd4","required":false,"desc":"VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"55c8c16d229b981900ed5fd3","required":false,"desc":"Can be either 'automatic' or 'manual'.","default":"automatic","type":"string","name":"collection_method"},{"_id":"55c8c16d229b981900ed5fd2","required":false,"desc":"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":"","type":"int","name":"net_terms"},{"_id":"55c8c16d229b981900ed5fd1","required":false,"desc":"Optional notes field. Attach a PO number to the invoice.","default":"","type":"string","name":"po_number"}],"results":{"codes":[{"status":201,"language":"xml","code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1005\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>open</state>\n  <invoice_number type=\"integer\">1005</invoice_number>\n  <po_number nil=\"nil\">34A-B324</po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">1200</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">1200</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0</tax_rate>\n  <net_terms type=\"integer\">30</net_terms>\n  <collection_method>manual</collection_method>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\"/>\n      <!-- Detail. -->\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>","name":""}]},"settings":"","url":"/accounts/:account_code/invoices"},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:12:51.925Z","excerpt":"When you post one-time charges to an account, these will remain pending until they are invoiced. An account is automatically invoiced when the subscription renews. However, there are times when it is appropriate to invoice an account before the renewal. If the subscriber has a yearly subscription, you might want to collect the one-time charges well before the renewal.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"project":"555fbba928249c1900618a82","slug":"post-an-invoice-invoice-pending-charges-on-an-acco","sync_unique":"","title":"Post an Invoice: Invoice Pending Charges on an Account","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postPost an Invoice: Invoice Pending Charges on an Account

When you post one-time charges to an account, these will remain pending until they are invoiced. An account is automatically invoiced when the subscription renews. However, there are times when it is appropriate to invoice an account before the renewal. If the subscriber has a yearly subscription, you might want to collect the one-time charges well before the renewal.

terms_and_conditions:
String
Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.
customer_notes:
String
Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
String
VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.
collection_method:
Stringautomatic
Can be either 'automatic' or 'manual'.
net_terms:
Integer
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.
po_number:
String
Optional notes field. Attach a PO number to the invoice.
[block:callout] { "type": "warning", "body": "This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "body": "This API call will return the new invoice's details on success. If there are no pending charges, it will return an HTTP status code of `422 Unprocessable Entity`." } [/block]
{"__v":7,"_id":"5595cb2cd4c23b0d00adf729","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $invoice = Recurly_Invoice::get('1327');\n  $invoice->markSuccessful();\n\n  print \"Invoice: $invoice\";\n} catch (Recurly_ValidationError $e) {\n  print \"Could not mark paid: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice not found: $e\";\n}","language":"php"},{"code":"invoice = Recurly::Invoice.find('1402')\ninvoice.mark_successful","language":"ruby"},{"code":"invoice = Invoice.get('1402')\ninvoice.mark_successful()","language":"python"},{"code":"var invoice = Invoices.Get(1005);\ninvoice.MarkSuccessful();","language":"csharp"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1402\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <address>\n      <address1>400 Alabama St.</address1>\n      <address2></address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94110</zip>\n      <country>US</country>\n      <phone></phone>\n    </address>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>collected</state>\n  <invoice_number_prefix></invoice_number_prefix> <!-- Only populated for VAT Country Invoice Sequencing. Shows a country code. -->\n  <invoice_number type=\"integer\">1402</invoice_number>\n  <po_number nil=\"nil\"></po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">9900</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">9900</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0</tax_rate>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\"/>\n      <!-- Detail. -->\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>"}]},"settings":"","url":"/invoices/:invoice_number/mark_successful"},"body":"","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:16:11.429Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"project":"555fbba928249c1900618a82","slug":"mark-an-invoice-as-paid-successfully","sync_unique":"","title":"Mark an Invoice as Paid Successfully","type":"put","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

putMark an Invoice as Paid Successfully


Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":5,"_id":"5595cb2cd4c23b0d00adf72a","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $invoice = Recurly_Invoice::get('1340');\n  $invoice->markFailed();\n\n  print \"Invoice: $invoice\";\n} catch (Recurly_ValidationError $e) {\n  print \"Could not mark failed: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice not found: $e\";\n}","name":""},{"language":"ruby","code":"invoice = Recurly::Invoice.find('e3f0a9e084a2468480d00ee61b090d4d')\ninvoice.mark_failed"},{"language":"python","code":"invoice = Invoice.get('e3f0a9e084a2468480d00ee61b090d4d')\ninvoice.mark_failed()"},{"language":"csharp","code":"var invoice = Invoices.Get(1005);\ninvoice.MarkFailed();"}]},"params":[],"results":{"codes":[{"code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1001\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <address>\n      <address1>400 Alabama St.</address1>\n      <address2></address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>94110</zip>\n      <country>US</country>\n      <phone></phone>\n    </address>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>failed</state>\n  <invoice_number_prefix></invoice_number_prefix> <!-- Only populated for VAT Country Invoice Sequencing. Shows a country code. -->\n  <invoice_number type=\"integer\">1402</invoice_number>\n  <po_number nil=\"nil\"></po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">9900</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">9900</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0</tax_rate>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\"/>\n      <!-- Detail. -->\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>","language":"xml","status":200}]},"settings":"","url":"/invoices/:invoice_number/mark_failed"},"body":"","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:16:28.049Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":8,"project":"555fbba928249c1900618a82","slug":"mark-an-invoice-as-failed-collection","sync_unique":"","title":"Mark an Invoice as Failed Collection","type":"put","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

putMark an Invoice as Failed Collection


Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":9,"_id":"5595cb2cd4c23b0d00adf72b","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $invoice = Recurly_Invoice::get('1341'); // get some invoice\n  $line_items = $invoice->line_items;      // get line items\n\n  // use Recurly_Adjustment->toRefundAttributes() to\n  // turn the line items you want into refund objects\n  // you can optionally pass in `prorated` and `quantity`\n  $adjustments = array_map(\n    function($line_item) { return $line_item->toRefundAttributes(); },\n    $invoice->line_items\n  );\n\n  // pass the refund attributes to the refund() method\n  // returns a new Recurly_Invoice\n  $refund_invoice = $invoice->refund($adjustments);\n  $refund_invoice->subtotal_in_cents; // -1000\n\n  print \"Refund Invoice: $refund_invoice\";\n} catch (Recurly_ValidationError $e) {\n  // There is a problem with the data or the invoice can't be refunded\n  print \"Validation Error: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice not found: $e\";\n}\n\nThere is an alternative way to call refund directly on an adjustment\ntry {\n  // grab some adjustment\n  $adjustment = Recurly_Adjustment::get('2fe89a073a31318cab377e464cb811b4');\n\n  // you can optionally pass in the same arguments as toRefundAttributes\n  // return Recurly_Invoice\n  $refund_invoice = $adjustment->refund();\n  $refund_invoice->subtotal_in_cents; // -1000\n\n  print \"Refund Invoice: $refund_invoice\";\n} catch (Recurly_ValidationError $e) {\n  // There is a problem with the data or the invoice can't be refunded\n  print \"Validation Error: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Adjustment not found: $e\";\n}","language":"php"},{"code":"invoice = Invoice.find(1005)\nadjustments = invoice.line_items.values.map do |adjustment|\n  { adjustment: adjustment, quantity: 1, prorate: false }\nend\n\ninvoice.refund adjustments","language":"ruby"},{"code":"invoice = Invoice.get('1005')\nline_items = list({'adjustment' : adjustment, 'quantity' : 1, 'prorate' : False} for adjustment in invoice.line_items)\n\nrefund_invoice = invoice.refund(line_items)","language":"python"},{"code":"// refund a single adjustment\nvar invoice = Invoices.Get(1005);\nvar adjustment = invoice.Adjustments.First(x => x.Uuid == \"e1234245132465\");\ninvoice = invoice.Refund(adjustment, false, 1); // adjustment, prorate, quantity\n\n// refund multiple adjustments\nvar invoice = Invoices.Get(1005);\ninvoice.Refund(invoice.Adjustments);","language":"csharp"},{"code":"<invoice>\n  <line_items>\n    <adjustment>\n      <uuid>2bc33a7469dc1458f455634212acdcd6</uuid>\n      <quantity>1</quantity>\n      <prorate>false</prorate>\n    </adjustment>\n    <adjustment>\n      <uuid>2bc33a746a89d867df47024fd6b261b6</uuid>\n      <quantity>1</quantity>\n      <prorate>true</prorate>\n    </adjustment>\n  </line_items>\n</invoice>","language":"xml"}]},"params":[],"results":{"codes":[{"name":"","code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1010\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <uuid>2bc3cf4cbe357b7525eac5424292b445</uuid>\n  <state>collected</state>\n  <invoice_number type=\"integer\">1010</invoice_number>\n  <po_number nil=\"nil\"/>\n  <vat_number nil=\"nil\"/>\n  <subtotal_in_cents type=\"integer\">-9771</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">-9771</total_in_cents>\n  <currency>GBP</currency>\n  <created_at type=\"datetime\">2014-12-16T21:32:16Z</created_at>\n  <closed_at type=\"datetime\">2014-12-16T21:32:16Z</closed_at>\n  <terms_and_conditions nil=\"nil\"/>\n  <customer_notes nil=\"nil\"/>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/2bc3cf4cb513049c6aec1b419c97b508\" type=\"charge\">\n      <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n      <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1010\"/>\n      <uuid>2bc3cf4cb513049c6aec1b419c97b508</uuid>\n      <state>invoiced</state>\n      <description>Refund for Setup fee: IP Addresses</description>\n      <accounting_code nil=\"nil\"/>\n      <product_code>ipaddresses</product_code>\n      <origin>setup_fee</origin>\n      <unit_amount_in_cents type=\"integer\">900</unit_amount_in_cents>\n      <quantity type=\"integer\">-1</quantity>\n      <quantity_remaining type=\"integer\">0</quantity_remaining>\n      <discount_in_cents type=\"integer\">0</discount_in_cents>\n      <tax_in_cents type=\"integer\">0</tax_in_cents>\n      <total_in_cents type=\"integer\">-900</total_in_cents>\n      <currency>GBP</currency>\n      <taxable type=\"boolean\">false</taxable>\n      <tax_exempt type=\"boolean\">false</tax_exempt>\n      <tax_code nil=\"nil\"/>\n      <start_date type=\"datetime\">2014-12-16T18:49:41Z</start_date>\n      <end_date nil=\"nil\"/>\n      <created_at type=\"datetime\">2014-12-16T21:32:16Z</created_at>\n    </adjustment>\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/2bc3cf4cb615aea5540bb54d4c9fc814\" type=\"charge\">\n      <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n      <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1010\"/>\n      <uuid>2bc3cf4cb615aea5540bb54d4c9fc814</uuid>\n      <state>invoiced</state>\n      <description>Refund for IP Addresses</description>\n      <accounting_code nil=\"nil\"/>\n      <product_code>ipaddresses</product_code>\n      <origin>plan</origin>\n      <unit_amount_in_cents type=\"integer\">8871</unit_amount_in_cents>\n      <quantity type=\"integer\">-1</quantity>\n      <quantity_remaining type=\"integer\">0</quantity_remaining>\n      <discount_in_cents type=\"integer\">0</discount_in_cents>\n      <tax_in_cents type=\"integer\">0</tax_in_cents>\n      <total_in_cents type=\"integer\">-8871</total_in_cents>\n      <currency>GBP</currency>\n      <taxable type=\"boolean\">false</taxable>\n      <tax_exempt type=\"boolean\">false</tax_exempt>\n      <tax_code nil=\"nil\"/>\n      <start_date type=\"datetime\">2014-12-16T21:32:16Z</start_date>\n      <end_date type=\"datetime\">2015-01-16T18:49:41Z</end_date>\n      <created_at type=\"datetime\">2014-12-16T21:32:16Z</created_at>\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n    <!-- Omitted -->\n  </transactions>\n</invoice>","language":"xml","status":201}]},"settings":"","url":"/invoices/:invoice_number/refund"},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"An invoice with a processed line item refund cannot accept refunds of an open amount.\\n\\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI.\"\n}\n[/block]\n**REFUND ATTRIBUTES**\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`uuid`\",\n    \"0-1\": \"Unique adjustment ID.**`required`**\",\n    \"1-0\": \"`quantity`\",\n    \"1-1\": \"Quantity of the line item to refund.**`required`**\",\n    \"2-0\": \"`prorate`\",\n    \"2-1\": \"Toggle to prorate the line item to refund. Set as `true` or `false`. Only applicable to subscription line items still in the current billing cycle. Proration is not allowed on invoices with an associated transaction that has not settled, due to the full amount needed in order to void the transaction.\",\n    \"3-0\": \"`refund_apply_order`\",\n    \"3-1\": \"If credit line items exist on the invoice, this parameter specifies which refund method to use first. Most relevant in a partial refunds, you can chose to refund credit back to the account first or a transaction giving money back to the customer first. If not specified, the default is credit back to the account. Set as `credit` or `transaction`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:20:32.509Z","excerpt":"Allows specific invoice line items and/or quantities to be refunded and generates a refund invoice. Full amount line item refunds of invoices with an unsettled transaction will void the transaction and generate a void invoice.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":9,"project":"555fbba928249c1900618a82","slug":"line-item-refunds","sync_unique":"","title":"Line Item Refunds/Voids","type":"post","updates":["55b66ee1f8105a2f00c34f37"],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postLine Item Refunds/Voids

Allows specific invoice line items and/or quantities to be refunded and generates a refund invoice. Full amount line item refunds of invoices with an unsettled transaction will void the transaction and generate a void invoice.

[block:callout] { "type": "warning", "body": "An invoice with a processed line item refund cannot accept refunds of an open amount.\n\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI." } [/block] **REFUND ATTRIBUTES** [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "`uuid`", "0-1": "Unique adjustment ID.**`required`**", "1-0": "`quantity`", "1-1": "Quantity of the line item to refund.**`required`**", "2-0": "`prorate`", "2-1": "Toggle to prorate the line item to refund. Set as `true` or `false`. Only applicable to subscription line items still in the current billing cycle. Proration is not allowed on invoices with an associated transaction that has not settled, due to the full amount needed in order to void the transaction.", "3-0": "`refund_apply_order`", "3-1": "If credit line items exist on the invoice, this parameter specifies which refund method to use first. Most relevant in a partial refunds, you can chose to refund credit back to the account first or a transaction giving money back to the customer first. If not specified, the default is credit back to the account. Set as `credit` or `transaction`." }, "cols": 2, "rows": 4 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "body": "An invoice with a processed line item refund cannot accept refunds of an open amount.\n\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI." } [/block] **REFUND ATTRIBUTES** [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "`uuid`", "0-1": "Unique adjustment ID.**`required`**", "1-0": "`quantity`", "1-1": "Quantity of the line item to refund.**`required`**", "2-0": "`prorate`", "2-1": "Toggle to prorate the line item to refund. Set as `true` or `false`. Only applicable to subscription line items still in the current billing cycle. Proration is not allowed on invoices with an associated transaction that has not settled, due to the full amount needed in order to void the transaction.", "3-0": "`refund_apply_order`", "3-1": "If credit line items exist on the invoice, this parameter specifies which refund method to use first. Most relevant in a partial refunds, you can chose to refund credit back to the account first or a transaction giving money back to the customer first. If not specified, the default is credit back to the account. Set as `credit` or `transaction`." }, "cols": 2, "rows": 4 } [/block]
{"__v":6,"_id":"5595cb2cd4c23b0d00adf72c","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $invoice = Recurly_Invoice::get('1346');\n  $refund_invoice = $invoice->refundAmount(1000); // refund in cents, returns a  Recurly_Invoice\n  $refund_invoice->subtotal_in_cents;             // -1000\n\n  print \"Refund Invoice: $refund_invoice\";\n} catch (Recurly_ValidationError $e) {\n  // Data is invalid or the invoice could not be refunded\n  print \"Invoice could not be refunded: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invoice Not Found: $e\";\n}","name":""},{"language":"ruby","code":"invoice = Invoice.find(1005)\ninvoice.refund_amount 10_00"},{"language":"python","code":"invoice = Invoice.get('1001')\nrefund_invoice = invoice.refund_amount(1000)"},{"language":"csharp","code":"var invoice = Invoices.Get(1005);\nvar refundInvoice = invoice.RefundAmount(1000);"},{"language":"xml","code":"<invoice>\n  <amount_in_cents>1000</amount_in_cents>\n</invoice>"}]},"params":[{"_id":"55c8c72071d7580d0063a5c8","required":false,"desc":"The specific amount to be refunded from the original invoice. If left empty, the remaining refundable amount will be refunded.","default":"","type":"int","name":"amount_in_cents"},{"_id":"55c8c72071d7580d0063a5c7","required":false,"desc":"If credit line items exist on the invoice, this parameter specifies which refund method to use first. Most relevant in a partial refunds, you can chose to refund credit back to the account first or a transaction giving money back to the customer first. Set as `credit` or `transaction`.","default":"credit","type":"string","name":"refund_apply_order"}],"results":{"codes":[{"status":201,"language":"xml","code":"<invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1010\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <address>\n    <address1>400 Alabama Street</address1>\n    <address2>Suite 202</address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94110</zip>\n    <country>US</country>\n    <phone></phone>\n  </address>\n  <original_invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1005\"/>\n  <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n  <state>collected</state>\n  <invoice_number type=\"integer\">1010</invoice_number>\n  <po_number nil=\"nil\"></po_number>\n  <vat_number nil=\"nil\"></vat_number>\n  <subtotal_in_cents type=\"integer\">-1000</subtotal_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <total_in_cents type=\"integer\">-1000</total_in_cents>\n  <currency>USD</currency>\n  <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n  <closed_at nil=\"nil\"></closed_at>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <amount_remaining_in_cents type=\"integer\">9000</amount_remaining_in_cents>\n  <line_items type=\"array\">\n    <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/05a4bbdeda2a47348185270021e6087b\" type=\"charge\">\n      <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n      <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1010\"/>\n      <uuid>2529f8eeec94a858bd8268461f8f1b30</uuid>\n      <state>invoiced</state>\n      <description>Refund for Invoice #1009</description>\n      <accounting_code></accounting_code>\n      <product_code>ipaddresses</product_code>\n      <origin>add_on</origin>\n      <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n      <quantity type=\"integer\">-1</quantity>\n      <quantity_remaining type=\"integer\">0</quantity_remaining>\n      <discount_in_cents type=\"integer\">0</discount_in_cents>\n      <tax_in_cents type=\"integer\">0</tax_in_cents>\n      <total_in_cents type=\"integer\">-1000</total_in_cents>\n      <currency>USD</currency>\n      <tax_exempt type=\"boolean\">false</tax_exempt>\n      <start_date type=\"datetime\">2011-08-25T12:00:00Z</start_date>\n      <end_date nil=\"nil\"></end_date>\n      <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n    </adjustment>\n  </line_items>\n  <transactions type=\"array\">\n  </transactions>\n</invoice>","name":""}]},"settings":"","url":"/invoices/:invoice_number/refund"},"body":"[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"An invoice with a processed open amount refund cannot accept [line item](/v2.0/docs/line-item-refunds) refunds.\\n\\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T17:31:15.021Z","excerpt":"Allows custom invoice amounts to be refunded and generates a refund invoice. Full open amount refunds of invoices with an unsettled transaction will void the transaction and generate a void invoice.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":10,"project":"555fbba928249c1900618a82","slug":"open-amount-refunds","sync_unique":"","title":"Open Amount Refunds/Voids","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postOpen Amount Refunds/Voids

Allows custom invoice amounts to be refunded and generates a refund invoice. Full open amount refunds of invoices with an unsettled transaction will void the transaction and generate a void invoice.

amount_in_cents:
Integer
The specific amount to be refunded from the original invoice. If left empty, the remaining refundable amount will be refunded.
refund_apply_order:
Stringcredit
If credit line items exist on the invoice, this parameter specifies which refund method to use first. Most relevant in a partial refunds, you can chose to refund credit back to the account first or a transaction giving money back to the customer first. Set as `credit` or `transaction`.
[block:callout] { "type": "warning", "body": "An invoice with a processed open amount refund cannot accept [line item](/v2.0/docs/line-item-refunds) refunds.\n\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "warning", "body": "An invoice with a processed open amount refund cannot accept [line item](/v2.0/docs/line-item-refunds) refunds.\n\nThis endpoint will not void an ACH bank account transaction. ACH voids are only allowed through the UI." } [/block]
{"__v":5,"_id":"5595cb2cd4c23b0d00adf72d","api":{"auth":"required","examples":{"codes":[{"language":"xml","code":"<transaction>\n <payment_method>check</payment_method>\n <collected_at>2011-08-25T12:00:00Z</collected_at>\n <amount_in_cents>1000</amount_in_cents>\n <description>Paid with a check</description>\n</transaction>","name":""}]},"params":[{"_id":"55c547c77136a60d002aa88f","required":true,"desc":"The method of payment. \"credit_card\", \"paypal\", \"eft\", \"wire_transfer\", \"money_order\", \"check\", or \"other\".","default":"","type":"string","name":"payment_method"},{"_id":"55c547c77136a60d002aa88e","required":false,"desc":"Date payment was collected.","default":"","type":"string","name":"collected_at"},{"_id":"55c547c77136a60d002aa88d","required":false,"desc":"The amount paid in cents.","default":"","type":"string","name":"amount_in_cents"},{"_id":"55c547c77136a60d002aa88c","required":false,"desc":"Note for the manual payment. Max 50 characters.","default":"","type":"string","name":"description"}],"results":{"codes":[{"name":"","code":"<transaction href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>\n  <action>purchase</action>\n  <amount_in_cents type=\"integer\">1000</amount_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <currency>USD</currency>\n  <status>success</status>\n  <payment_method>check</payment_method>\n  <reference nil=\"nil\"/>\n  <source>transaction</source>\n  <recurring type=\"boolean\">false</recurring>\n  <test type=\"boolean\">true</test>\n  <voidable type=\"boolean\">true</voidable>\n  <refundable type=\"boolean\">true</refundable>\n  <ip_address nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-06-19T03:01:33Z</created_at>\n  <details>\n    <account>\n      <account_code>1</account_code>\n      <first_name nil=\"nil\"/>\n      <last_name nil=\"nil\"/>\n        <address1>123 Main St.</address1>\n        <address2 nil=\"nil\"/>\n        <city>San Francisco</city>\n        <state>CA</state>\n        <zip>94105</zip>\n        <country>US</country>\n        <phone nil=\"nil\"/>\n        <vat_number nil=\"nil\"/>\n      </billing_info>\n    </account>\n  </details>\n  <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" method=\"delete\"/>\n</transaction>","language":"xml","status":201}]},"settings":"","url":"/invoices/:invoice_number/transactions"},"body":"","category":"5595cb2ad4c23b0d00adf6ee","createdAt":"2015-06-18T18:24:39.853Z","excerpt":"Allows you to enter an offline payment for a manual invoice, such as a check or money order.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":11,"project":"555fbba928249c1900618a82","slug":"enter-an-offline-payment-for-a-manual-invoice-beta","sync_unique":"","title":"Enter an Offline Payment for a Manual Invoice (Beta)","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postEnter an Offline Payment for a Manual Invoice (Beta)

Allows you to enter an offline payment for a manual invoice, such as a check or money order.

payment_method:
required
String
The method of payment. "credit_card", "paypal", "eft", "wire_transfer", "money_order", "check", or "other".
collected_at:
String
Date payment was collected.
amount_in_cents:
String
The amount paid in cents.
description:
String
Note for the manual payment. Max 50 characters.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf71d","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$plans = Recurly_PlanList::get();\nforeach ($plans as $plan) {\n  print \"Plan: $plan\\n\";\n}","name":""},{"language":"ruby","code":"Recurly::Plan.find_each do |plan|\n  puts \"Plan: #{plan.inspect}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\nplans = Plan.all()\nwhile plans:\n    for plan in plans:\n        print 'Plan: %s' % plan\n    try:\n        plans = plans.next_page()\n    except PageError:\n        plans = ()\n\n#client version 2.1.6+\nfor plan in Plan.all():\n    print 'Plan: %s' % plan"},{"language":"csharp","code":"using System.Linq;\n\nvar plans = Plans.List();\nwhile (plans.Any())\n{\n\tforeach (var plan in plans)\n\t\tConsole.WriteLine(\"Plan: \" + plan);\n\tplans = plans.Next;\n}"}]},"params":[{"_id":"55830ff6b806360d0024496c","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"55830ff6b806360d0024496b","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"int","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<plans type=\"array\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n    <description nil=\"nil\"/>\n    <success_url nil=\"nil\"/>\n    <cancel_url nil=\"nil\"/>\n    <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n    <display_quantity type=\"boolean\">false</display_quantity>\n    <display_phone_number type=\"boolean\">false</display_phone_number>\n    <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n    <unit_name>unit</unit_name>\n    <payment_page_tos_link nil=\"nil\"/>\n    <plan_interval_length type=\"integer\">1</plan_interval_length>\n    <plan_interval_unit>months</plan_interval_unit>\n    <trial_interval_length type=\"integer\">0</trial_interval_length>\n    <trial_interval_unit>days</trial_interval_unit>\n    <total_billing_cycles nil=\"nil\"/>\n    <accounting_code nil=\"nil\"/>\n    <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n    <tax_exempt type=\"boolean\">false</tax_exempt>\n    <tax_code nil=\"nil\"/>\n    <unit_amount_in_cents>\n      <USD type=\"integer\">6000</USD>\n      <EUR type=\"integer\">4500</EUR>\n    </unit_amount_in_cents>\n    <setup_fee_in_cents>\n      <USD type=\"integer\">1000</USD>\n      <EUR type=\"integer\">800</EUR>\n    </setup_fee_in_cents>\n  </plan>\n  <!-- Continued... -->\n</plans>","name":""}]},"settings":"","url":"/plans"},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ef","createdAt":"2015-06-18T18:37:42.850Z","excerpt":"Lists all your active subscription plans.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"list-plans","sync_unique":"","title":"List Plans","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getList Plans

Lists all your active subscription plans.

cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
Integer50
Number of records to return per page, up to a maximum of 200.
[block:callout] { "type": "info", "body": "The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "info", "body": "The client library will automatically fetch the next page of the results. There may be a slight delay when fetching the next page." } [/block]
{"__v":5,"_id":"5595cb2cd4c23b0d00adf71e","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $plan = Recurly_Plan::get('gold');\n  print \"Plan: $plan\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan not found\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')"},{"language":"python","code":"plan = Plan.get('gold')"},{"language":"csharp","code":"var plan = Plans.Get(\"gold\");"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <EUR type=\"integer\">4500</EUR>\n    <USD type=\"integer\">6000</USD>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <EUR type=\"integer\">800</EUR>\n    <USD type=\"integer\">1000</USD>\n  </setup_fee_in_cents>\n</plan>","name":""}]},"settings":"","url":"/plans/:plan_code"},"body":"","category":"5595cb2ad4c23b0d00adf6ef","createdAt":"2015-06-18T18:41:50.557Z","excerpt":"Lookup a plan's details.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"lookup-plan-details","sync_unique":"","title":"Lookup Plan Details","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup Plan Details

Lookup a plan's details.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"5595cb2cd4c23b0d00adf71f","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $plan = new Recurly_Plan();\n  $plan->plan_code = 'gold';\n  $plan->name = \"Gold plan\";\n  $plan->unit_amount_in_cents->addCurrency('USD', 1000); // USD 10.00 month\n  $plan->unit_amount_in_cents->addCurrency('EUR', 800);  // EUR 8.00 month\n  $plan->setup_fee_in_cents->addCurrency('USD', 6000); // USD 60.00 setup fee\n  $plan->setup_fee_in_cents->addCurrency('EUR', 4500); // EUR 45.00 setup fee\n  $plan->plan_interval_length = 1;\n  $plan->plan_interval_unit = 'months';\n  $plan->tax_exempt = false;\n  $plan->create();\n\n  print \"Plan: $plan\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Data: $e\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.create(\n  :plan_code            => 'gold',\n  :name                 => 'Gold plan',\n  :unit_amount_in_cents => { 'USD' => 10_00, 'EUR' => 8_00 },\n  :setup_fee_in_cents   => { 'USD' => 60_00, 'EUR' => 45_00 },\n  :plan_interval_length => 1,\n  :plan_interval_unit   => 'months'\n  :tax_exempt           => false\n)"},{"language":"python","code":"plan = Plan(plan_code='gold', name='Gold plan')\nplan.unit_amount_in_cents = Money(USD=1000, EUR=800)\nplan.setup_fee_in_cents = Money(USD=6000, EUR=4500)\nplan.plan_interval_length = 1\nplan.plan_interval_unit = 'months'\nplan.tax_exempt = False\nplan.save()"},{"language":"csharp","code":"var plan = new Plan(\"gold\", \"Gold plan\"); // plan code, name\nplan.UnitAmountInCents.Add(\"USD\", 1000);\nplan.UnitAmountInCents.Add(\"EUR\", 800);\nplan.SetupFeeInCents.Add(\"USD\", 6000);\nplan.SetupFeeInCents.Add(\"EUR\", 4500);\nplan.PlanIntervalLength = 1;\nplan.PlanIntervalUnit = Plan.IntervalUnit.Month;\nplan.TaxExempt = false;\nplan.Create();"},{"language":"xml","code":"<plan>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <unit_amount_in_cents>\n    <USD>6000</USD>\n    <EUR>4500</EUR>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <USD>1000</USD>\n    <EUR>800</EUR>\n  </setup_fee_in_cents>\n  <plan_interval_length>1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <tax_exempt>false</tax_exempt>\n</plan>"}]},"params":[{"_id":"55831249ea39a9390022435b","required":true,"desc":"Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.","default":"","type":"string","name":"plan_code"},{"_id":"55831249ea39a9390022435a","required":true,"desc":"Plan name. Max of 255 characters.","default":"","type":"string","name":"name"},{"_id":"55831249ea39a93900224352","required":true,"desc":"Array of currency objects, see example below. Max 10000000.","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"55831249ea39a93900224359","required":false,"desc":"Optional plan description, not displayed","default":"","type":"string","name":"description"},{"_id":"55831249ea39a93900224358","required":false,"desc":"Accounting code for related invoice line items, code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 20 characters.","default":"","type":"string","name":"accounting_code"},{"_id":"55831249ea39a93900224357","required":false,"desc":"\"days\", or \"months\", defaults to \"months\"","default":"","type":"string","name":"plan_interval_unit"},{"_id":"55831249ea39a93900224356","required":false,"desc":"Plan interval length, defaults to 1","default":"1","type":"int","name":"plan_interval_length"},{"_id":"55831249ea39a93900224355","required":false,"desc":"days\", or \"months\", defaults to \"months\"","default":"months","type":"string","name":"trial_interval_unit"},{"_id":"55831249ea39a93900224354","required":false,"desc":"Defaults to zero, or no trial","default":"0","type":"int","name":"trial_interval_length"},{"_id":"55831249ea39a93900224353","required":false,"desc":"Array of currency objects, see examples. Max 10000000.","default":"","type":"array_int","name":"setup_fee_in_cents"},{"_id":"55d7617bf662951900fc0e76","required":false,"desc":"Accounting code for a Setup Fee, code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 20 characters.","default":"","type":"string","name":"setup_fee_accounting_code"},{"_id":"55831249ea39a93900224351","required":false,"desc":"Number of billing cycles before the plan stops renewing, defaults to null for continuous auto renewal.","default":"null","type":"string","name":"total_billing_cycles"},{"_id":"55831249ea39a93900224350","required":false,"desc":"Unit description for the quantity, e.g. \"users\".","default":"","type":"string","name":"unit_name"},{"_id":"55831249ea39a9390022434f","required":false,"desc":"Display the quantity field on the hosted payment page if true, defaults to false.","default":"false","type":"boolean","name":"display_quantity"},{"_id":"55831249ea39a9390022434e","required":false,"desc":"URL to redirect to after signup on the hosted payment pages.","default":"","type":"string","name":"success_url"},{"_id":"55831249ea39a9390022434d","required":false,"desc":"URL to redirect to on canceled signup on the hosted payment pages.","default":"","type":"string","name":"cancel_url"},{"_id":"55831249ea39a9390022434c","required":false,"desc":"`true` exempts tax on the plan, `false` applies tax on the plan. If not defined, then defaults to the Plan and Site settings.","default":"","type":"boolean","name":"tax_exempt"},{"_id":"55831249ea39a9390022434b","required":false,"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.","default":"","type":"string","name":"tax_code"}],"results":{"codes":[{"status":201,"language":"xml","code":"<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">6000</USD>\n    <EUR type=\"integer\">4500</EUR>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <USD type=\"integer\">1000</USD>\n    <EUR type=\"integer\">800</EUR>\n  </setup_fee_in_cents>\n</plan>","name":""}]},"settings":"","url":"/plans"},"body":"","category":"5595cb2ad4c23b0d00adf6ef","createdAt":"2015-06-18T18:47:37.527Z","excerpt":"Create a new subscription plan.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"create-plan","sync_unique":"","title":"Create Plan","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postCreate Plan

Create a new subscription plan.

plan_code:
required
String
Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.
name:
required
String
Plan name. Max of 255 characters.
unit_amount_in_cents:
required
Integer
Array of currency objects, see example below. Max 10000000.
description:
String
Optional plan description, not displayed
accounting_code:
String
Accounting code for related invoice line items, code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 20 characters.
plan_interval_unit:
String
"days", or "months", defaults to "months"
plan_interval_length:
Integer1
Plan interval length, defaults to 1
trial_interval_unit:
Stringmonths
days", or "months", defaults to "months"
trial_interval_length:
Integer0
Defaults to zero, or no trial
setup_fee_in_cents:
Array of Integers
Array of currency objects, see examples. Max 10000000.
setup_fee_accounting_code:
String
Accounting code for a Setup Fee, code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 20 characters.
total_billing_cycles:
Stringnull
Number of billing cycles before the plan stops renewing, defaults to null for continuous auto renewal.
unit_name:
String
Unit description for the quantity, e.g. "users".
display_quantity:
Booleanfalse
Display the quantity field on the hosted payment page if true, defaults to false.
success_url:
String
URL to redirect to after signup on the hosted payment pages.
cancel_url:
String
URL to redirect to on canceled signup on the hosted payment pages.
tax_exempt:
Boolean
`true` exempts tax on the plan, `false` applies tax on the plan. If not defined, then defaults to the Plan and Site settings.
tax_code:
String
Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":6,"_id":"5595cb2cd4c23b0d00adf720","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $plan = Recurly_Plan::get('gold');\n  $plan->unit_amount_in_cents['EUR'] = 5000; // EUR 50.00 monthly fee\n  $plan->setup_fee_in_cents['EUR'] = 5000; // EUR 50.00 setup fee\n  $plan->update();\n\n  print \"Plan: $plan\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')\nplan.setup_fee_in_cents['EUR'] = 50_00\nplan.save"},{"language":"python","code":"plan = Plan.get('gold')\nplan.setup_fee_in_cents['EUR'] = 5000\nplan.save()"},{"language":"csharp","code":"var plan = Plans.Get(\"gold\");\nplan.SetupFeeInCents[\"EUR\"] = 5000;\nplan.Update();"},{"language":"xml","code":"<plan>\n  <setup_fee_in_cents>\n    <USD>6000</USD>\n    <EUR>5000</EUR>\n  </setup_fee_in_cents>\n</plan>"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n  <add_ons href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons\"/>\n  <plan_code>gold</plan_code>\n  <name>Gold plan</name>\n  <description nil=\"nil\"/>\n  <success_url nil=\"nil\"/>\n  <cancel_url nil=\"nil\"/>\n  <display_donation_amounts type=\"boolean\">false</display_donation_amounts>\n  <display_quantity type=\"boolean\">false</display_quantity>\n  <display_phone_number type=\"boolean\">false</display_phone_number>\n  <bypass_hosted_confirmation type=\"boolean\">false</bypass_hosted_confirmation>\n  <unit_name>unit</unit_name>\n  <payment_page_tos_link nil=\"nil\"/>\n  <plan_interval_length type=\"integer\">1</plan_interval_length>\n  <plan_interval_unit>months</plan_interval_unit>\n  <trial_interval_length type=\"integer\">0</trial_interval_length>\n  <trial_interval_unit>days</trial_interval_unit>\n  <total_billing_cycles nil=\"nil\"/>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-05-29T17:38:15Z</created_at>\n  <tax_exempt type=\"boolean\">false</tax_exempt>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <EUR type=\"integer\">4500</EUR>\n    <USD type=\"integer\">6000</USD>\n  </unit_amount_in_cents>\n  <setup_fee_in_cents>\n    <EUR type=\"integer\">5000</EUR>\n    <USD type=\"integer\">6000</USD>\n  </setup_fee_in_cents>\n</plan>","name":""}]},"settings":"","url":"/plans/:plan_code"},"body":"","category":"5595cb2ad4c23b0d00adf6ef","createdAt":"2015-06-18T18:50:40.401Z","excerpt":"Update the pricing or details for a plan. Existing subscriptions will remain at the previous renewal amounts.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"update-plan","sync_unique":"","title":"Update Plan","type":"put","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Plan

Update the pricing or details for a plan. Existing subscriptions will remain at the previous renewal amounts.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":6,"_id":"5595cb2cd4c23b0d00adf721","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $plan = Recurly_Plan::get('gold');\n  $plan->delete();\n\n  print \"Plan: $plan\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}","language":"php"},{"code":"plan = Recurly::Plan.find('gold')\nplan.destroy","language":"ruby"},{"code":"plan = Plan.get('gold')\nplan.delete()","language":"python"},{"code":"var plan = Plans.Get(\"gold\");\nplan.Deactivate();","language":"csharp"}]},"params":[],"results":{"codes":[{"status":204,"language":"xml","code":"Status: 204 No Content"}]},"settings":"","url":"/plans/:plan_code"},"body":"","category":"5595cb2ad4c23b0d00adf6ef","createdAt":"2015-06-18T18:52:18.177Z","excerpt":"Deleting a plan makes it inactive. New subscriptions cannot be created from the plan.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"delete-plan","sync_unique":"","title":"Delete Plan","type":"delete","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

deleteDelete Plan

Deleting a plan makes it inactive. New subscriptions cannot be created from the plan.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf710","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $plan = Recurly_Plan::get('gold');\n  $add_ons = $plan->add_ons->get();\n  // Or, in 1 API request:\n  // $add_ons = Recurly_AddonsList::get('gold');\n  foreach ($add_ons as $add_on) {\n    print \"Add-on: $add_on\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')\nplan.add_ons.find_each do |add_on|\n  puts \"Add-on: #{add_on.inspect}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\nplan = Plan.get('gold')\nadd_ons = plan.add_ons()\nwhile add_ons:\n    for add_on in add_ons:\n        print 'Add-on: %s' % add_on\n    try:\n        add_ons = add_ons.next_page()\n    except PageError:\n        add_ons = ()\n\n#client version 2.1.6+\nplan = Plan.get('gold')\nfor add_on in plan.add_ons():\n    print 'Add-on: %s' % add_on"},{"language":"csharp","code":"using System.Linq;\n\nvar plan = Plans.Get(\"gold\");\nvar addons = plan.AddOns;\nwhile (addons.Any())\n{\n\tforeach (var addon in addons)\n\t\tConsole.WriteLine(\"Addon: \" + addon);\n\taddons = addons.Next;\n}"}]},"params":[{"_id":"55831de9ea39a9390022439e","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"55831de9ea39a9390022439d","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"string","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<add_ons type=\"array\">\n  <add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n    <add_on_code>ipaddresses</add_on_code>\n    <name>IP Addresses</name>\n    <default_quantity type=\"integer\">1</default_quantity>\n    <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n    <tax_code>digital</tax_code>\n    <unit_amount_in_cents>\n      <USD type=\"integer\">200</USD>\n    </unit_amount_in_cents>\n    <accounting_code>abc123</accounting_code>\n    <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n  </add_on>\n  <!-- Continued... -->\n</add_ons>","name":""}]},"settings":"","url":"/plans/:plan_code/add_ons"},"body":"","category":"5595cb2ad4c23b0d00adf6f0","createdAt":"2015-06-18T19:37:13.453Z","excerpt":"Returns a list of all the add-ons for a plan.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-add-ons-for-a-plan","sync_unique":"","title":"List Add-Ons for a Plan","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getList Add-Ons for a Plan

Returns a list of all the add-ons for a plan.

cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
String50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2cd4c23b0d00adf711","api":{"auth":"required","examples":{"codes":[{"language":"csharp","code":"var plan = Plans.Get(\"gold\");\nvar addon = plan.GetAddOn(\"addOnCode\");","name":""}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code>digital</tax_code>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">200</USD>\n  </unit_amount_in_cents>\n  <accounting_code>abc123</accounting_code>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>","name":""}]},"settings":"","url":"/:plan_code/add_ons/:addon_code"},"body":"**ATTRIBUTES**\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`add_on_code`\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-1\": \"Add on code.\",\n    \"1-0\": \"`name`\",\n    \"1-1\": \"Add on name.\",\n    \"2-0\": \"`unit_amount_in_cents`\",\n    \"2-1\": \"Array of unit amounts for currencies.\",\n    \"3-0\": \"`default_quantity`\",\n    \"3-1\": \"Default quantity for the hosted pages, defaults to 1.\",\n    \"4-0\": \"`display_quantity_on_hosted_page`\",\n    \"4-1\": \"If true, display a quantity field on the hosted pages for the addon.\",\n    \"5-0\": \"`created_at`\",\n    \"5-1\": \"Date the add-on was created.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6f0","createdAt":"2015-06-18T19:47:37.395Z","excerpt":"Returns information about an add-on.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"lookup-an-add-on","sync_unique":"","title":"Lookup an Add-On","type":"get","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

getLookup an Add-On

Returns information about an add-on.

**ATTRIBUTES** [block:parameters] { "data": { "0-0": "`add_on_code`", "h-0": "Attribute", "h-1": "Description", "0-1": "Add on code.", "1-0": "`name`", "1-1": "Add on name.", "2-0": "`unit_amount_in_cents`", "2-1": "Array of unit amounts for currencies.", "3-0": "`default_quantity`", "3-1": "Default quantity for the hosted pages, defaults to 1.", "4-0": "`display_quantity_on_hosted_page`", "4-1": "If true, display a quantity field on the hosted pages for the addon.", "5-0": "`created_at`", "5-1": "Date the add-on was created." }, "cols": 2, "rows": 6 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



**ATTRIBUTES** [block:parameters] { "data": { "0-0": "`add_on_code`", "h-0": "Attribute", "h-1": "Description", "0-1": "Add on code.", "1-0": "`name`", "1-1": "Add on name.", "2-0": "`unit_amount_in_cents`", "2-1": "Array of unit amounts for currencies.", "3-0": "`default_quantity`", "3-1": "Default quantity for the hosted pages, defaults to 1.", "4-0": "`display_quantity_on_hosted_page`", "4-1": "If true, display a quantity field on the hosted pages for the addon.", "5-0": "`created_at`", "5-1": "Date the add-on was created." }, "cols": 2, "rows": 6 } [/block]
{"__v":3,"_id":"5595cb2cd4c23b0d00adf712","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $add_on = new Recurly_Addon();\n  $add_on->plan_code = 'gold';\n  $add_on->add_on_code = 'ipaddresses';\n  $add_on->name = 'Extra IP Addresses';\n  $add_on->unit_amount_in_cents->addCurrency('USD', 200);\n  $add_on->create();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Addon data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan Not Found: $e\";\n}\n","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')\nadd_on = plan.add_ons.create(\n  :add_on_code          => 'ipaddresses',\n  :name                 => 'Extra IP Addresses',\n  :unit_amount_in_cents => 2_00\n)"},{"language":"python","code":"plan = Plan.get('gold')\naddon = AddOn(\n  add_on_code='ipaddresses',\n  name='Extra IP Addresses',\n  unit_amount_in_cents=200\n)\nplan.create_add_on(addon)"},{"language":"csharp","code":"var plan = Plans.Get(\"gold\");\nvar addon = plan.NewAddOn(\"ipaddresses\", \"Extra IP Addresses\"); // add-on code, name\naddon.UnitAmountInCents.Add(\"USD\", 200);\naddon.DefaultQuantity = 1;\naddon.DisplayQuantityOnHostedPage = true;\naddon.Create();\n\n// accounting_code not yet supported.\n// Please contact us if you need this."},{"language":"xml","code":"<add_on>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <unit_amount_in_cents>\n    <USD>200</USD>\n  </unit_amount_in_cents>\n</add_on>"}]},"params":[{"_id":"55c548635c5d9f0d004969c6","required":false,"desc":"Add On Code. Max of 50 characters.","default":"","type":"string","name":"add_on_code"},{"_id":"55c548635c5d9f0d004969c5","required":false,"desc":"Add-on name. Max of 255 characters.","default":"","type":"string","name":"name"},{"_id":"55c548635c5d9f0d004969c4","required":false,"desc":"Array of unit amounts for currencies. Max 10000000.","default":"","type":"string","name":"unit_amount_in_cents"},{"_id":"55c548635c5d9f0d004969c3","required":false,"desc":"Default quantity for the hosted pages","default":"1","type":"string","name":"default_quantity"},{"_id":"55c548635c5d9f0d004969c2","required":false,"desc":"If true, display a quantity field on the hosted pages for the add-on","default":"","type":"string","name":"display_quantity_on_hosted_page"},{"_id":"55c548635c5d9f0d004969c1","required":false,"desc":"Accounting code for invoice line items for the add-on, defaults to add_on_code. Max of 20 characters.","default":"","type":"string","name":"accounting_code"},{"_id":"55c548635c5d9f0d004969c0","required":false,"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.","default":"","type":"string","name":"tax_code"}],"results":{"codes":[{"name":"","code":"<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">200</USD>\n  </unit_amount_in_cents>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>","language":"xml","status":201}]},"settings":"","url":"/plans/:plan_code/add_ons"},"body":"","category":"5595cb2ad4c23b0d00adf6f0","createdAt":"2015-06-18T19:50:44.924Z","excerpt":"Add an add-on to a plan.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-an-add-on","sync_unique":"","title":"Create an Add-On","type":"post","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

postCreate an Add-On

Add an add-on to a plan.

add_on_code:
String
Add On Code. Max of 50 characters.
name:
String
Add-on name. Max of 255 characters.
unit_amount_in_cents:
String
Array of unit amounts for currencies. Max 10000000.
default_quantity:
String1
Default quantity for the hosted pages
display_quantity_on_hosted_page:
String
If true, display a quantity field on the hosted pages for the add-on
accounting_code:
String
Accounting code for invoice line items for the add-on, defaults to add_on_code. Max of 20 characters.
tax_code:
String
Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":6,"_id":"5595cb2cd4c23b0d00adf713","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $add_on = Recurly_Addon::get('gold', 'ipaddresses'); // (plan_code, addon_code)\n  $add_on->unit_amount_in_cents['USD']->amount_in_cents = 1200; // $12.00.\n  $add_on->update();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Addon data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan or Addon Not Found: $e\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')\nadd_on = plan.add_ons.find('ipaddresses')\nadd_on.update_attributes :unit_amount_in_cents => 12_00"},{"language":"python","code":"plan = Plan.get('gold')\nadd_on = plan.get_add_on('ipaddresses')\nadd_on.unit_amount_in_cents = 200\nadd_on.save()"},{"language":"csharp","code":"var plan = Plans.Get(\"gold\");\nvar addon = plan.GetAddOn(\"ipaddresses\");\naddon.UnitAmountInCents[\"USD\"] = 200;\naddon.Update();\n "},{"language":"xml","code":"<add_on>\n  <unit_amount_in_cents>\n    <USD>1200</USD>\n  </unit_amount_in_cents>\n</add_on>"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<add_on href=\"https://your-subdomain.recurly.com/v2/plans/gold/add_ons/ipaddresses\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\"/>\n  <add_on_code>ipaddresses</add_on_code>\n  <name>Extra IP Addresses</name>\n  <default_quantity type=\"integer\">1</default_quantity>\n  <display_quantity_on_hosted_page type=\"boolean\">false</display_quantity_on_hosted_page>\n  <tax_code nil=\"nil\"/>\n  <unit_amount_in_cents>\n    <USD type=\"integer\">1200</USD>\n  </unit_amount_in_cents>\n  <accounting_code nil=\"nil\"/>\n  <created_at type=\"datetime\">2011-06-28T12:34:56Z</created_at>\n</add_on>","name":""}]},"settings":"","url":"/plans/:plan_code/add_ons/:add_on_code"},"body":"","category":"5595cb2ad4c23b0d00adf6f0","createdAt":"2015-06-18T19:59:54.118Z","excerpt":"Update the pricing information or description for an add-on. Subscriptions who have already subscribed to the add-on will not receive the new pricing.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"update-an-add-on","sync_unique":"","title":"Update an Add-On","type":"put","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate an Add-On

Update the pricing information or description for an add-on. Subscriptions who have already subscribed to the add-on will not receive the new pricing.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":3,"_id":"5595cb2cd4c23b0d00adf714","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $add_on = Recurly_Addon::get('gold', 'ipaddresses'); // (plan_code, addon_code)\n  $add_on->delete();\n\n  print \"Addon: $add_on\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Plan or Addon Not Found: $e\";\n}","name":""},{"language":"ruby","code":"plan = Recurly::Plan.find('gold')\nadd_on = plan.add_ons.find('ipaddresses')\nadd_on.destroy"},{"language":"python","code":"plan = Plan.get('gold')\nadd_on = plan.get_add_on('ipaddresses')\nadd_on.delete()"},{"language":"csharp","code":"var plan = Plans.Get(\"gold\");\nvar addon = plan.GetAddOn(\"ipaddresses\");\naddon.Delete();"}]},"params":[],"results":{"codes":[{"status":204,"language":"json","code":"Status: 204 No Content","name":""}]},"settings":"","url":"/plans/:plan_code/add_ons/:add_on_code"},"body":"","category":"5595cb2ad4c23b0d00adf6f0","createdAt":"2015-06-18T20:01:20.016Z","excerpt":"Remove an add-on from a plan.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"555fbba928249c1900618a82","slug":"delete-an-add-on","sync_unique":"","title":"Delete an Add-On","type":"delete","updates":[],"user":"5581f6648625220d00429ef6","version":"5595cb29d4c23b0d00adf6e3"}

deleteDelete an Add-On

Remove an add-on from a plan.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"5595cb2cd4c23b0d00adf733","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$subscriptions = Recurly_SubscriptionList::getActive();\nforeach ($subscriptions as $subscription) {\n  print \"Subscription: $subscription\\n\";\n}","name":""},{"language":"ruby","code":"Recurly::Subscription.find_each do |subscription|\n  puts \"Susbcription: #{subscription}\"\nend"},{"language":"python","code":"#client version <= 2.1.5\nsubscriptions = Subscription.all()\nwhile subscriptions:\n    for subscription in subscriptions:\n        print 'Subscription: %s' % subscription\n    try:\n        subscriptions = subscriptions.next_page()\n    except PageError:\n        subscriptions = ()\n\n#client version 2.1.6+\nfor subscription in Subscription.all():\n    print 'Subscription: %s' % subscription"},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar subscriptions = account.GetSubscriptions();\nwhile (subscriptions.Any())\n{\n  foreach (var subscription in subscriptions)\n    Console.WriteLine(\"Subscription: \" + subscription);\n  subscriptions = subscriptions.Next;\n}"}]},"params":[{"_id":"558219b8b806360d00244640","required":false,"desc":"The state of subscriptions to return: \"active\", \"canceled\", \"expired\", \"future\", \"in_trial\", \"live\", or \"past_due\". A subscription may belong to more than one state.","default":"","type":"string","name":"state"},{"_id":"558219b8b806360d0024463f","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"558219b8b806360d0024463e","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"string","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<subscriptions type=\"array\">\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n      <plan_code>gold</plan_code>\n      <name>Gold plan</name>\n    </plan>\n    <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n    <state>active</state>\n    <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n    <currency>EUR</currency>\n    <quantity type=\"integer\">1</quantity>\n    <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n    <canceled_at nil=\"nil\"></canceled_at>\n    <expires_at nil=\"nil\"></expires_at>\n    <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n    <trial_started_at nil=\"nil\"></trial_started_at>\n    <trial_ends_at nil=\"nil\"></trial_ends_at>\n    <tax_in_cents type=\"integer\">72</tax_in_cents>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.0875</tax_rate>\n    <po_number nil=\"nil\"></po_number>\n    <net_terms type=\"integer\">0</net_terms>\n    <subscription_add_ons type=\"array\">\n    </subscription_add_ons>\n    <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n    <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n    <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n  </subscription>\n  <!-- Continued... -->\n</subscriptions>","name":""}]},"settings":"","url":"/subscriptions"},"body":"###Subscription Query States\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"state\",\n    \"h-1\": \"description\",\n    \"0-0\": \"active\",\n    \"0-1\": \"Subscriptions that are valid for the current time. This includes subscriptions in a trial period\",\n    \"1-0\": \"canceled\",\n    \"1-1\": \"Subscriptions that are valid for the current time but will not renew because a cancelation was requested\",\n    \"2-0\": \"expired\",\n    \"2-1\": \"Subscriptions that have expired and are no longer valid\",\n    \"3-0\": \"future\",\n    \"3-1\": \"Subscriptions that will start in the future, they are not active yet\",\n    \"4-0\": \"in_trial\",\n    \"4-1\": \"Subscriptions that are active or canceled and are in a trial period\",\n    \"5-0\": \"live\",\n    \"5-1\": \"All subscriptions that are not expired\",\n    \"6-0\": \"past_due\",\n    \"6-1\": \"Subscriptions that are active or canceled and have a past-due invoice\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"\",\n  \"body\": \"Please note: a queried state and the base state of a returned subscription may differ. For example, querying for past_due subscriptions will not result in a list of subscriptions with a 'past_due' state (they will either be 'active' or 'canceled'). Only base states ('pending', 'active', 'canceled', 'expired', 'future') will be present in the returned subscription records.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:07:04.439Z","excerpt":"Returns a list of all the subscriptions.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"list-subscriptions","sync_unique":"","title":"List Subscriptions","type":"get","updates":["55b102d96c91eb2d008712bf"],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getList Subscriptions

Returns a list of all the subscriptions.

state:
String
The state of subscriptions to return: "active", "canceled", "expired", "future", "in_trial", "live", or "past_due". A subscription may belong to more than one state.
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
String50
Number of records to return per page, up to a maximum of 200.
###Subscription Query States [block:parameters] { "data": { "h-0": "state", "h-1": "description", "0-0": "active", "0-1": "Subscriptions that are valid for the current time. This includes subscriptions in a trial period", "1-0": "canceled", "1-1": "Subscriptions that are valid for the current time but will not renew because a cancelation was requested", "2-0": "expired", "2-1": "Subscriptions that have expired and are no longer valid", "3-0": "future", "3-1": "Subscriptions that will start in the future, they are not active yet", "4-0": "in_trial", "4-1": "Subscriptions that are active or canceled and are in a trial period", "5-0": "live", "5-1": "All subscriptions that are not expired", "6-0": "past_due", "6-1": "Subscriptions that are active or canceled and have a past-due invoice" }, "cols": 2, "rows": 7 } [/block] [block:callout] { "type": "warning", "title": "", "body": "Please note: a queried state and the base state of a returned subscription may differ. For example, querying for past_due subscriptions will not result in a list of subscriptions with a 'past_due' state (they will either be 'active' or 'canceled'). Only base states ('pending', 'active', 'canceled', 'expired', 'future') will be present in the returned subscription records." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



###Subscription Query States [block:parameters] { "data": { "h-0": "state", "h-1": "description", "0-0": "active", "0-1": "Subscriptions that are valid for the current time. This includes subscriptions in a trial period", "1-0": "canceled", "1-1": "Subscriptions that are valid for the current time but will not renew because a cancelation was requested", "2-0": "expired", "2-1": "Subscriptions that have expired and are no longer valid", "3-0": "future", "3-1": "Subscriptions that will start in the future, they are not active yet", "4-0": "in_trial", "4-1": "Subscriptions that are active or canceled and are in a trial period", "5-0": "live", "5-1": "All subscriptions that are not expired", "6-0": "past_due", "6-1": "Subscriptions that are active or canceled and have a past-due invoice" }, "cols": 2, "rows": 7 } [/block] [block:callout] { "type": "warning", "title": "", "body": "Please note: a queried state and the base state of a returned subscription may differ. For example, querying for past_due subscriptions will not result in a list of subscriptions with a 'past_due' state (they will either be 'active' or 'canceled'). Only base states ('pending', 'active', 'canceled', 'expired', 'future') will be present in the returned subscription records." } [/block]
{"__v":0,"_id":"5595cb2cd4c23b0d00adf734","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"<?php\ntry {\n  $subscriptions = Recurly_SubscriptionList::getForAccount('b6f5783');\n  foreach ($subscriptions as $subscription) {\n    print \"Subscription: $subscription\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Account Not Found: $e\";\n}\n?>","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.subscriptions.find_each do |subscription|\n  puts \"Subscription: #{subscription.inspect}\"\nend"},{"language":"python","code":"#client version 2.1.6+\naccount = Account.get('1')\nfor subscription in account.subscriptions():\n    print 'Subscription: %s' % subscription\n\n#client version <= 2.1.5\naccount = Account.get('1')\nsubscriptions = account.subscriptions()\nwhile subscriptions:\n    for subscription in subscriptions:\n        print 'Subscription: %s' % subscription\n    try:\n        subscriptions = subscriptions.next_page()\n    except PageError:\n        subscriptions = ()"},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar subscriptions = account.GetSubscriptions();\nwhile (subscriptions.Any())\n{\n  foreach (var subscription in subscriptions)\n    Console.WriteLine(\"Subscription: \" + subscription);\n  subscriptions = subscriptions.Next;\n}"}]},"params":[{"_id":"55821a9e5b7fa60d0068b421","required":false,"desc":"The state of subscriptions to return: \"active\", \"canceled\", \"expired\", \"future\", \"in_trial\", \"live\", or \"past_due\". A subscription may belong to more than one state. Please see the previous section for a note on subscription states.","default":"live","type":"string","name":"state"},{"_id":"55821a9e5b7fa60d0068b420","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"55821a9e5b7fa60d0068b41f","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"string","name":"per_page"}],"results":{"codes":[{"name":"","code":"<subscriptions type=\"array\">\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f3b96d\n99067eb08904457a9180eb\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/4568526784588812\"/\n>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1768\"/>\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/plic\">\n      <plan_code>plic</plan_code>\n      <name>Premium Licence</name>\n    </plan>\n    <uuid>3053f3b96d99067eb08904457a9180eb</uuid>\n    <state>active</state>\n    <unit_amount_in_cents type=\"integer\">24995</unit_amount_in_cents>\n    <currency>USD</currency>\n    <quantity type=\"integer\">1</quantity>\n    <activated_at type=\"datetime\">2015-07-31T17:28:31Z</activated_at>\n    <canceled_at nil=\"nil\"></canceled_at>\n    <expires_at nil=\"nil\"></expires_at>\n    <total_billing_cycles nil=\"nil\"></total_billing_cycles>\n    <remaining_billing_cycles nil=\"nil\"></remaining_billing_cycles>\n    <current_period_started_at type=\"datetime\">2015-07-31T17:28:31Z</current_per\niod_started_at>\n    <current_period_ends_at type=\"datetime\">2016-07-31T17:28:31Z</current_period\n_ends_at>\n    <trial_started_at nil=\"nil\"></trial_started_at>\n    <trial_ends_at nil=\"nil\"></trial_ends_at>\n    <terms_and_conditions></terms_and_conditions>\n    <customer_notes></customer_notes>\n    <tax_in_cents type=\"integer\">2250</tax_in_cents>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.09</tax_rate>\n    <po_number></po_number>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <subscription_add_ons type=\"array\">\n    </subscription_add_ons>\n    <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f\n3b96d99067eb08904457a9180eb/cancel\" method=\"put\"/>\n    <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/30\n53f3b96d99067eb08904457a9180eb/terminate\" method=\"put\"/>\n    <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/305\n3f3b96d99067eb08904457a9180eb/postpone\" method=\"put\"/>\n    <a name=\"notes\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f3\nb96d99067eb08904457a9180eb/notes\" method=\"put\"/>\n  </subscription>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f29711\nd5aa94abd0244df2832937\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/4568526784588812\"/\n>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1767\"/>\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/pro\">\n      <plan_code>pro</plan_code>\n      <name>Pro</name>\n    </plan>\n    <uuid>3053f29711d5aa94abd0244df2832937</uuid>\n    <state>active</state>\n    <unit_amount_in_cents type=\"integer\">3000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <quantity type=\"integer\">1</quantity>\n    <activated_at type=\"datetime\">2015-07-31T17:27:17Z</activated_at>\n    <canceled_at nil=\"nil\"></canceled_at>\n    <expires_at nil=\"nil\"></expires_at>\n    <total_billing_cycles nil=\"nil\"></total_billing_cycles>\n    <remaining_billing_cycles nil=\"nil\"></remaining_billing_cycles>\n    <current_period_started_at type=\"datetime\">2015-07-31T17:27:17Z</current_per\niod_started_at>\n    <current_period_ends_at type=\"datetime\">2015-08-31T17:27:17Z</current_period\n_ends_at>\n    <trial_started_at nil=\"nil\"></trial_started_at>\n    <trial_ends_at nil=\"nil\"></trial_ends_at>\n    <terms_and_conditions></terms_and_conditions>\n    <customer_notes></customer_notes>\n    <tax_in_cents type=\"integer\">270</tax_in_cents>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.09</tax_rate>\n    <po_number></po_number>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <subscription_add_ons type=\"array\">\n    </subscription_add_ons>\n    <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f\n29711d5aa94abd0244df2832937/cancel\" method=\"put\"/>\n    <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/30\n53f29711d5aa94abd0244df2832937/terminate\" method=\"put\"/>\n    <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/305\n3f29711d5aa94abd0244df2832937/postpone\" method=\"put\"/>\n    <a name=\"notes\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/3053f2\n9711d5aa94abd0244df2832937/notes\" method=\"put\"/>\n  </subscription>\n</subscriptions>","language":"xml","status":200}]},"settings":"","url":"/accounts/:account_code/subscriptions"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:10:54.210Z","excerpt":"Returns a list of subscriptions for an account.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-accounts-subscriptions","sync_unique":"","title":"List Account's Subscriptions","type":"get","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getList Account's Subscriptions

Returns a list of subscriptions for an account.

state:
Stringlive
The state of subscriptions to return: "active", "canceled", "expired", "future", "in_trial", "live", or "past_due". A subscription may belong to more than one state. Please see the previous section for a note on subscription states.
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
String50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":7,"_id":"5595cb2cd4c23b0d00adf735","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");"}]},"params":[],"results":{"codes":[{"name":"","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n  <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n</subscription>","language":"xml","status":200}]},"settings":"","url":"/subscriptions/:uuid"},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.\",\n  \"title\": \"PENDING SUBSCRIPTION CHANGES\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Subscription Parameters\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"plan\",\n    \"0-1\": \"Nested plan_code and plan name\",\n    \"1-0\": \"uuid\",\n    \"1-1\": \"Unique subscription ID\",\n    \"2-0\": \"state\",\n    \"2-1\": \"`active`, `canceled`, `future`, `expired`\",\n    \"3-0\": \"unit_amount_in_cents\",\n    \"3-1\": \"Unit amount of the subscription\",\n    \"4-1\": \"Number of units\",\n    \"5-1\": \"3-letter ISO currency for the subscription\",\n    \"6-1\": \"Date the subscription started\",\n    \"7-1\": \"Date the subscription was marked canceled\",\n    \"8-1\": \"Date the subscription will end (if state is `canceled`) or ended (if state is `expired`)\",\n    \"9-1\": \"Date the current bill cycle started\",\n    \"10-1\": \"Date the current bill cycle will end\",\n    \"11-1\": \"Date the trial was started, if applicable\",\n    \"12-1\": \"Date the trial ended, if applicable\",\n    \"13-1\": \"Amount of tax or VAT within the transaction, in cents.\",\n    \"14-1\": \"Tax type as \\\"vat\\\" for VAT or \\\"usst\\\" for US Sales Tax.\",\n    \"15-1\": \"Region where taxes are applied.\",\n    \"16-1\": \"Tax rate that will be applied to this subscription.\",\n    \"17-1\": \"PO number reference.\",\n    \"18-1\": \"Invoice net terms in days.\",\n    \"19-1\": \"Invoice collection as \\\"automatic\\\" or \\\"manual\\\".\",\n    \"20-1\": \"Nested list of add-ons on the subscription, if applicable\",\n    \"21-1\": \"Nested information about a pending subscription change at renewal\",\n    \"22-1\": \"Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.\",\n    \"23-1\": \"Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.\",\n    \"24-1\": \"Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist.\",\n    \"25-1\": \"**Description**\",\n    \"26-1\": \"Nested information about the new plan\",\n    \"27-1\": \"New subscription's unit amount in cents\",\n    \"28-1\": \"New subscription quantity\",\n    \"29-1\": \"Nested list of add-ons\",\n    \"29-0\": \"subscription_add_ons\",\n    \"28-0\": \"quantity\",\n    \"26-0\": \"plan\",\n    \"27-0\": \"unit_amount_in_cents\",\n    \"25-0\": \"**Subscription Parameters**\",\n    \"24-0\": \"bank_account_authorized_at\",\n    \"23-0\": \"customer_notes\",\n    \"22-0\": \"terms_and_conditions\",\n    \"21-0\": \"pending_subscription\",\n    \"20-0\": \"subscription_add_ons\",\n    \"19-0\": \"collection_method\",\n    \"18-0\": \"net_terms\",\n    \"17-0\": \"po_number\",\n    \"16-0\": \"tax_rate\",\n    \"15-0\": \"tax_region\",\n    \"14-0\": \"tax_type\",\n    \"13-0\": \"tax_in_cents\",\n    \"12-0\": \"trial_ends_at\",\n    \"11-0\": \"trial_started_at\",\n    \"10-0\": \"current_period_ends_at\",\n    \"9-0\": \"current_period_started_at\",\n    \"8-0\": \"expires_at\",\n    \"7-0\": \"canceled_at\",\n    \"6-0\": \"activated_at\",\n    \"5-0\": \"currency\",\n    \"4-0\": \"quantity\"\n  },\n  \"cols\": 2,\n  \"rows\": 30\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:22:21.025Z","excerpt":"Lookup a subscription's details.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"lookup-subscription-details","sync_unique":"","title":"Lookup Subscription Details","type":"get","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getLookup Subscription Details

Lookup a subscription's details.

[block:callout] { "type": "info", "body": "When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.", "title": "PENDING SUBSCRIPTION CHANGES" } [/block] [block:parameters] { "data": { "h-0": "Subscription Parameters", "h-1": "Description", "0-0": "plan", "0-1": "Nested plan_code and plan name", "1-0": "uuid", "1-1": "Unique subscription ID", "2-0": "state", "2-1": "`active`, `canceled`, `future`, `expired`", "3-0": "unit_amount_in_cents", "3-1": "Unit amount of the subscription", "4-1": "Number of units", "5-1": "3-letter ISO currency for the subscription", "6-1": "Date the subscription started", "7-1": "Date the subscription was marked canceled", "8-1": "Date the subscription will end (if state is `canceled`) or ended (if state is `expired`)", "9-1": "Date the current bill cycle started", "10-1": "Date the current bill cycle will end", "11-1": "Date the trial was started, if applicable", "12-1": "Date the trial ended, if applicable", "13-1": "Amount of tax or VAT within the transaction, in cents.", "14-1": "Tax type as \"vat\" for VAT or \"usst\" for US Sales Tax.", "15-1": "Region where taxes are applied.", "16-1": "Tax rate that will be applied to this subscription.", "17-1": "PO number reference.", "18-1": "Invoice net terms in days.", "19-1": "Invoice collection as \"automatic\" or \"manual\".", "20-1": "Nested list of add-ons on the subscription, if applicable", "21-1": "Nested information about a pending subscription change at renewal", "22-1": "Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.", "23-1": "Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.", "24-1": "Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist.", "25-1": "**Description**", "26-1": "Nested information about the new plan", "27-1": "New subscription's unit amount in cents", "28-1": "New subscription quantity", "29-1": "Nested list of add-ons", "29-0": "subscription_add_ons", "28-0": "quantity", "26-0": "plan", "27-0": "unit_amount_in_cents", "25-0": "**Subscription Parameters**", "24-0": "bank_account_authorized_at", "23-0": "customer_notes", "22-0": "terms_and_conditions", "21-0": "pending_subscription", "20-0": "subscription_add_ons", "19-0": "collection_method", "18-0": "net_terms", "17-0": "po_number", "16-0": "tax_rate", "15-0": "tax_region", "14-0": "tax_type", "13-0": "tax_in_cents", "12-0": "trial_ends_at", "11-0": "trial_started_at", "10-0": "current_period_ends_at", "9-0": "current_period_started_at", "8-0": "expires_at", "7-0": "canceled_at", "6-0": "activated_at", "5-0": "currency", "4-0": "quantity" }, "cols": 2, "rows": 30 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "info", "body": "When looking up a subscription that has pending changes, the new subscription details will be in a pending_subscription node. Since immediate subscription changes take place immediately, pending subscription changes will only show for changes occurring when the subscription renews.", "title": "PENDING SUBSCRIPTION CHANGES" } [/block] [block:parameters] { "data": { "h-0": "Subscription Parameters", "h-1": "Description", "0-0": "plan", "0-1": "Nested plan_code and plan name", "1-0": "uuid", "1-1": "Unique subscription ID", "2-0": "state", "2-1": "`active`, `canceled`, `future`, `expired`", "3-0": "unit_amount_in_cents", "3-1": "Unit amount of the subscription", "4-1": "Number of units", "5-1": "3-letter ISO currency for the subscription", "6-1": "Date the subscription started", "7-1": "Date the subscription was marked canceled", "8-1": "Date the subscription will end (if state is `canceled`) or ended (if state is `expired`)", "9-1": "Date the current bill cycle started", "10-1": "Date the current bill cycle will end", "11-1": "Date the trial was started, if applicable", "12-1": "Date the trial ended, if applicable", "13-1": "Amount of tax or VAT within the transaction, in cents.", "14-1": "Tax type as \"vat\" for VAT or \"usst\" for US Sales Tax.", "15-1": "Region where taxes are applied.", "16-1": "Tax rate that will be applied to this subscription.", "17-1": "PO number reference.", "18-1": "Invoice net terms in days.", "19-1": "Invoice collection as \"automatic\" or \"manual\".", "20-1": "Nested list of add-ons on the subscription, if applicable", "21-1": "Nested information about a pending subscription change at renewal", "22-1": "Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.", "23-1": "Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.", "24-1": "Recurring subscriptions paid with ACH will have this attribute with an iso8601 timestamp value. This timestamp is used for alerting customers to reauthorize in 3 years in accordance with NACHA rules. If a subscription becomes inactive or the billing info is no longer a bank account, this timestamp is cleared and the attribute will not exist.", "25-1": "**Description**", "26-1": "Nested information about the new plan", "27-1": "New subscription's unit amount in cents", "28-1": "New subscription quantity", "29-1": "Nested list of add-ons", "29-0": "subscription_add_ons", "28-0": "quantity", "26-0": "plan", "27-0": "unit_amount_in_cents", "25-0": "**Subscription Parameters**", "24-0": "bank_account_authorized_at", "23-0": "customer_notes", "22-0": "terms_and_conditions", "21-0": "pending_subscription", "20-0": "subscription_add_ons", "19-0": "collection_method", "18-0": "net_terms", "17-0": "po_number", "16-0": "tax_rate", "15-0": "tax_region", "14-0": "tax_type", "13-0": "tax_in_cents", "12-0": "trial_ends_at", "11-0": "trial_started_at", "10-0": "current_period_ends_at", "9-0": "current_period_started_at", "8-0": "expires_at", "7-0": "canceled_at", "6-0": "activated_at", "5-0": "currency", "4-0": "quantity" }, "cols": 2, "rows": 30 } [/block]
{"__v":1,"_id":"5595cb2cd4c23b0d00adf736","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = new Recurly_Subscription();\n  $subscription->plan_code = 'gold';\n  $subscription->currency = 'EUR';\n\n  $account = new Recurly_Account();\n  $account->account_code = 'b6f5783';\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->month = 12;\n  $billing_info->year = 2017;\n  $billing_info->verification_value = 123;\n  $billing_info->address1 = '400 Alabama St';\n  $billing_info->city = 'San Francisco';\n  $billing_info->state = 'CA';\n  $billing_info->country = 'US';\n  $billing_info->zip = '94110';\n\n  $account->billing_info = $billing_info;\n  $subscription->account = $account;\n\n  $subscription->create();\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Plan, Subscription, Account, or BillingInfo data: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.create(\n  :plan_code => 'gold',\n  :currency  => 'EUR',\n  :customer_notes  => 'Thank you for your business!',\n  :account   => {\n    :account_code => '1',\n    :email        => 'verena@example.com',\n    :first_name   => 'Verena',\n    :last_name    => 'Example',\n    :billing_info => {\n      :number => '4111-1111-1111-1111',\n      :month  => 1,\n      :year   => 2014,\n    }\n  }\n)"},{"language":"python","code":"subscription = Subscription()\nsubscription.plan_code = 'gold'\nsubscription.currency = 'EUR'\n\naccount = Account(account_code='1')\naccount.email = 'verena@example.com'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\n\nbilling_info = BillingInfo()\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.month = 1\nbilling_info.year = 2014\n\naccount.billing_info = billing_info\nsubscription.account = account\n\nsubscription.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\"); // Account contains BillingInfo\nvar plan = Plans.Get(\"gold\");\nvar subscription = new Subscription(account, plan, \"USD\"); // account, plan, currency\nsubscription.Create();"},{"language":"xml","code":"<subscription>\n  <plan_code>gold</plan_code>\n  <currency>EUR</currency>\n  <account>\n    <account_code>1</account_code>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <billing_info>\n      <number>4111-1111-1111-1111</number>\n      <month>1</month>\n      <year>2014</year>\n    </billing_info>\n  </account>\n</subscription>"}]},"params":[{"_id":"55821f1f6f8ec90d00cf1a76","required":true,"desc":"plan_code for the subscription","default":"","type":"string","name":"plan_code"},{"_id":"55821f1f6f8ec90d00cf1a75","required":true,"desc":"nested account attributes","default":"","type":"object","name":"account"},{"_id":"55821f1f6f8ec90d00cf1a71","required":true,"desc":"Currency for the subscription","default":"","type":"string","name":"currency"},{"_id":"55821f1f6f8ec90d00cf1a74","required":false,"desc":"nested add ons","default":"","type":"array_mixed","name":"subscription_add_ons"},{"_id":"55821f1f6f8ec90d00cf1a73","required":false,"desc":"Optional coupon code to apply to the new subscription. Please note, the subscription request will fail if the coupon is invalid","default":"","type":"string","name":"coupon_code"},{"_id":"55821f1f6f8ec90d00cf1a72","required":false,"desc":"Override the unit amount of the subscription plan by setting this value in cents. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. Max 10000000.","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"55821f1f6f8ec90d00cf1a70","required":false,"desc":"Optionally override the default quantity of 1","default":"","type":"int","name":"quantity"},{"_id":"55821f1f6f8ec90d00cf1a6f","required":false,"desc":"If set, overrides the default trial behavior for the subscription. This must be a date and time, preferably in UTC. The date must be in the future.","default":"","type":"datetime","name":"trial_ends_at"},{"_id":"55821f1f6f8ec90d00cf1a6e","required":false,"desc":"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.","default":"","type":"datetime","name":"starts_at"},{"_id":"55821f1f6f8ec90d00cf1a6d","required":false,"desc":"Renews the subscription for a specified number of cycles, then automatically cancels. Defaults to the subscription renewing indefinitely.","default":"","type":"int","name":"total_billing_cycles"},{"_id":"55821f1f6f8ec90d00cf1a6c","required":false,"desc":"Indicates a date at which the first renewal should occur. Subsequent renewals will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies. Useful for forcing a subscription to renew on the first of the month.","default":"","type":"datetime","name":"first_renewal_date"},{"_id":"55821f1f6f8ec90d00cf1a6b","required":false,"desc":"Optional field to set the collection for an invoice as \"automatic\" or \"manual\". The default is \"automatic\" if it's not set.","default":"","type":"string","name":"collection_method"},{"_id":"55821f1f6f8ec90d00cf1a6a","required":false,"desc":"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. Defaults to '0'.","default":"0","type":"int","name":"net_terms"},{"_id":"55821f1f6f8ec90d00cf1a69","required":false,"desc":"Optional notes field. Attach a PO number to the invoice.","default":"","type":"string","name":"po_number"},{"_id":"55821f1f6f8ec90d00cf1a68","required":false,"desc":"Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API. Set to 'true' or 'false'. Defaults to 'false'.","default":"false","type":"boolean","name":"bulk"},{"_id":"55821f1f6f8ec90d00cf1a67","required":false,"desc":"Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"55821f1f6f8ec90d00cf1a66","required":false,"desc":"Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"customer_notes"},{"_id":"55821f1f6f8ec90d00cf1a65","required":false,"desc":"VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"},{"_id":"55821f1f6f8ec90d00cf1a64","required":false,"desc":"Merchants importing recurring subscriptions paid with ACH into Recurly can backdate the subscription's authorization with this attribute using an iso8601 timestamp. 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.","default":"","type":"timestamp","name":"bank_account_authorized_at"}],"results":{"codes":[{"status":201,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions"},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"SUBSCRIPTION STARTS DATE\"\n}\n[/block]\nIf you would like the subscription to start on a specified date, please set the `trial_ends_at` parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"CREATING AN ACCOUNT SIMULTANEOUSLY\"\n}\n[/block]\nTo avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"USING STORED BILLING INFO\"\n}\n[/block]\nYou may create a subscription without specifying billing information if an account already has stored billing information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"REDEEMING A COUPON\"\n}\n[/block]\nYou may optionally pass a coupon_code with the subscription request. The subscription will only be created if the coupon code is valid for the given plan. In the future, to change the coupon that is applied, you will have to remove this coupon from the corresponding account and redeem the new coupon.","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:30:07.720Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-subscription","sync_unique":"","title":"Create Subscription","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postCreate Subscription


plan_code:
required
String
plan_code for the subscription
account:
required
Object
nested account attributes
currency:
required
String
Currency for the subscription
subscription_add_ons:
Array of Mixed
nested add ons
coupon_code:
String
Optional coupon code to apply to the new subscription. Please note, the subscription request will fail if the coupon is invalid
unit_amount_in_cents:
Integer
Override the unit amount of the subscription plan by setting this value in cents. If not provided, the subscription will inherit the price from the subscription plan for the provided currency. Max 10000000.
quantity:
Integer
Optionally override the default quantity of 1
trial_ends_at:
DateTime
If set, overrides the default trial behavior for the subscription. This must be a date and time, preferably in UTC. The date must be in the future.
starts_at:
DateTime
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.
total_billing_cycles:
Integer
Renews the subscription for a specified number of cycles, then automatically cancels. Defaults to the subscription renewing indefinitely.
first_renewal_date:
DateTime
Indicates a date at which the first renewal should occur. Subsequent renewals will be offset from this date. The first invoice will be prorated appropriately so that the customer only pays for the portion of the first billing period for which the subscription applies. Useful for forcing a subscription to renew on the first of the month.
collection_method:
String
Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
net_terms:
Integer0
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. Defaults to '0'.
po_number:
String
Optional notes field. Attach a PO number to the invoice.
bulk:
Booleanfalse
Optional field to be used only when needing to bypass the 60 second limit on creating subscriptions. Should only be used when creating subscriptions in bulk from the API. Set to 'true' or 'false'. Defaults to 'false'.
terms_and_conditions:
String
Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals.
customer_notes:
String
Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
String
VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.
bank_account_authorized_at:
Timestamp
Merchants importing recurring subscriptions paid with ACH into Recurly can backdate the subscription's authorization with this attribute using an iso8601 timestamp. 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.
[block:api-header] { "type": "basic", "title": "SUBSCRIPTION STARTS DATE" } [/block] If you would like the subscription to start on a specified date, please set the `trial_ends_at` parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system. [block:api-header] { "type": "basic", "title": "CREATING AN ACCOUNT SIMULTANEOUSLY" } [/block] To avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription. [block:api-header] { "type": "basic", "title": "USING STORED BILLING INFO" } [/block] You may create a subscription without specifying billing information if an account already has stored billing information. [block:api-header] { "type": "basic", "title": "REDEEMING A COUPON" } [/block] You may optionally pass a coupon_code with the subscription request. The subscription will only be created if the coupon code is valid for the given plan. In the future, to change the coupon that is applied, you will have to remove this coupon from the corresponding account and redeem the new coupon.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "SUBSCRIPTION STARTS DATE" } [/block] If you would like the subscription to start on a specified date, please set the `trial_ends_at` parameter in your API request. Recurly will ignore any trial period currently specified on the plan and begin charging the subscription on the date specified. This is useful for creating your own, custom trial intervals and for importing existing subscriptions from an external system. [block:api-header] { "type": "basic", "title": "CREATING AN ACCOUNT SIMULTANEOUSLY" } [/block] To avoid paying multiple transaction fees, Recurly allows you to create a subscription, account and billing information in one API call. That way the billing information can be validated when charging for the subscription. [block:api-header] { "type": "basic", "title": "USING STORED BILLING INFO" } [/block] You may create a subscription without specifying billing information if an account already has stored billing information. [block:api-header] { "type": "basic", "title": "REDEEMING A COUPON" } [/block] You may optionally pass a coupon_code with the subscription request. The subscription will only be created if the coupon code is valid for the given plan. In the future, to change the coupon that is applied, you will have to remove this coupon from the corresponding account and redeem the new coupon.
{"__v":9,"_id":"5595cb2cd4c23b0d00adf737","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = new Recurly_Subscription();\n  $subscription->plan_code = 'gold';\n  $subscription->currency = 'USD';\n\n  $account = new Recurly_Account();\n  $account->account_code = 'b6f5783';\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->month = 12;\n  $billing_info->year = 2017;\n  $billing_info->verification_value = 123;\n  $billing_info->address1 = '400 Alabama St';\n  $billing_info->city = 'San Francisco';\n  $billing_info->state = 'CA';\n  $billing_info->country = 'US';\n  $billing_info->zip = '94110';\n\n  $account->billing_info = $billing_info;\n  $subscription->account = $account;\n\n  $subscription->preview();\n\n  // $subscription has been updated with new attributes\n  print \"$subscription->tax_in_cents\\n\";\n  print \"$subscription->cost_in_cents\\n\";\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Plan, Subscription, Account, or BillingInfo data: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.preview(\n  plan_code: 'gold',\n  currency: 'EUR',\n  account: {\n    account_code: '1',\n    email: 'verena@example.com',\n    first_name: 'Verena',\n    last_name: 'Example',\n    billing_info: {\n      number: '4111-1111-1111-1111',\n      month: 1,\n      year: 2014,\n    }\n  }\n)"},{"language":"python","code":"subscription = Subscription()\nsubscription.plan_code = 'gold'\nsubscription.currency = 'EUR'\n\naccount = Account(account_code='1')\naccount.email = 'verena@example.com'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\n\nbilling_info = BillingInfo()\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.month = 1\nbilling_info.year = 2014\n\naccount.billing_info = billing_info\nsubscription.account = account\n\nsubscription.preview()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar plan = Plans.Get(\"gold\");\nvar subscription = new Subscription(account, plan, \"USD\"); // account, plan, currency\nsubscription.Preview();"},{"language":"xml","code":"<subscription>\n  <plan_code>gold</plan_code>\n  <currency>USD</currency>\n  <account>\n    <account_code>1</account_code>\n    <email>verena@example.com</email>\n    <first_name>verena</first_name>\n    <last_name>example</last_name>\n  </account>\n</subscription>"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n  <plan href=\"https://you-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>pending</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>USD</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">72</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/preview"},"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"The Preview Subscription endpoint will return tax if your site's taxable customer address is provided in the call. This may be the Billing Information address or the Account Information address depending on your site settings. Tax previews are supported for both Recurly Basic taxes and if you are using your own Avalara account.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:37:29.227Z","excerpt":"Returns a preview for a new subscription applied to an account. See above for information on available/required parameters.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"preview-subscription","sync_unique":"","title":"Preview Subscription","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postPreview Subscription

Returns a preview for a new subscription applied to an account. See above for information on available/required parameters.

[block:callout] { "type": "info", "title": "", "body": "The Preview Subscription endpoint will return tax if your site's taxable customer address is provided in the call. This may be the Billing Information address or the Account Information address depending on your site settings. Tax previews are supported for both Recurly Basic taxes and if you are using your own Avalara account." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:callout] { "type": "info", "title": "", "body": "The Preview Subscription endpoint will return tax if your site's taxable customer address is provided in the call. This may be the Billing Information address or the Account Information address depending on your site settings. Tax previews are supported for both Recurly Basic taxes and if you are using your own Avalara account." } [/block]
{"__v":1,"_id":"5595cb2cd4c23b0d00adf738","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8c7aeb72f0257541b89405383ad69');\n  $subscription->plan_code = 'silver';\n  $subscription->quantity = 2;\n  $subscription->updateImmediately();     // Update immediately.\n  // or $subscription->updateAtRenewal(); // Update when the subscription renews.\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Subscription data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.update_attributes(\n  :plan_code => 'silver',\n  :quantity  => 2,\n  :timeframe => 'now'       # Update immediately.\n  # :timeframe => 'renewal' # Update when the subscription renews.\n)"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.plan_code = 'silver'\nsubscription.quantity = 2\nsubscription.timeframe = 'now'       # Update immediately.\n# subscription.timeframe = 'renewal' # Update when the subscription renews.\nsubscription.save()"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.Plan = Plans.Get(\"silver\");\nsubscription.Quantity = 2;\n\n// perform the update operation\nsubscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);\n\n// You might also use Subscription.ChangeTimeframe.Renewal"},{"language":"xml","code":"<subscription>\n  <timeframe>now</timeframe>\n  <quantity>2</quantity>\n  <subscription_add_ons>\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n</subscription>"}]},"params":[{"_id":"558222616f8ec90d00cf1a89","default":"now","desc":"\"now\" for immediate, \"renewal\" to perform when the subscription renews. defaults to \"now\" if not specified","name":"timeframe","required":false,"type":"string"},{"_id":"558222616f8ec90d00cf1a88","required":false,"desc":"New plan, remains unchanged if not specified","default":"","type":"string","name":"plan_code"},{"_id":"558222616f8ec90d00cf1a87","required":false,"desc":"New quantity, remains unchanged if not specified and the plan_code remains the same","default":"","type":"int","name":"quantity"},{"_id":"558222616f8ec90d00cf1a86","required":false,"desc":"New unit amount in cents","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"558222616f8ec90d00cf1a85","required":false,"desc":"Optional field to set the collection for an invoice as \"automatic\" or \"manual\". The default is \"automatic\" if it's not set.","default":"","type":"string","name":"collection_method"},{"_id":"558222616f8ec90d00cf1a84","default":"","desc":"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.","name":"net_terms","required":false,"type":"int"},{"_id":"558222616f8ec90d00cf1a83","required":false,"desc":"Optional notes field. Attach a PO number to the invoice.","default":"","type":"string","name":"po_number"},{"_id":"558222616f8ec90d00cf1a82","required":false,"desc":"Nested add-on information for the subscription, the new subscription will have no add-ons unless specified","default":"","type":"array_mixed","name":"subscription_add_ons"}],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <subscription_add_ons type=\"array\">\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/:uuid"},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"TIMEFRAME\"\n}\n[/block]\nThe timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now or when the subscription renews. 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 \"renewal\" so the change takes affect at the end of the current billing cycle.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"ADD-ONS\"\n}\n[/block]\nThe original subscription's add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T01:44:01.993Z","excerpt":"Request an update to a subscription that takes place immediately or at renewal.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":5,"project":"555fbba928249c1900618a82","slug":"update-subscription","sync_unique":"","title":"Update Subscription","type":"put","updates":["55b674bc6127b12500364486"],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Subscription

Request an update to a subscription that takes place immediately or at renewal.

timeframe:
Stringnow
"now" for immediate, "renewal" to perform when the subscription renews. defaults to "now" if not specified
plan_code:
String
New plan, remains unchanged if not specified
quantity:
Integer
New quantity, remains unchanged if not specified and the plan_code remains the same
unit_amount_in_cents:
Integer
New unit amount in cents
collection_method:
String
Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
net_terms:
Integer
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.
po_number:
String
Optional notes field. Attach a PO number to the invoice.
subscription_add_ons:
Array of Mixed
Nested add-on information for the subscription, the new subscription will have no add-ons unless specified
[block:api-header] { "type": "basic", "title": "TIMEFRAME" } [/block] The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now or when the subscription renews. 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 "renewal" so the change takes affect at the end of the current billing cycle. [block:api-header] { "type": "basic", "title": "ADD-ONS" } [/block] The original subscription's add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "TIMEFRAME" } [/block] The timeframe parameter controls when the upgrade or downgrade takes place. The subscription change can occur now or when the subscription renews. 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 "renewal" so the change takes affect at the end of the current billing cycle. [block:api-header] { "type": "basic", "title": "ADD-ONS" } [/block] The original subscription's add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.
{"__v":0,"_id":"5595cb2cd4c23b0d00adf739","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8c7aeb72f0257541b89405383ad69');\n\n  $subscription->updateNotes(array(\n    \"customer_notes\" => \"New Customer Notes\",\n    \"terms_and_conditions\" => \"New Terms\",\n    \"vat_reverse_charge_notes\" => \"New VAT Notes\"\n  ));\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","language":"php"},{"code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.update_notes(\n  customer_notes: 'New Customer Notes',\n  terms_and_conditions: 'New Terms',\n  vat_reverse_charge_notes: 'New VAT Notes'\n)","language":"ruby"},{"code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.update_notes(customer_notes='New Customer Notes',\n    terms_and_conditions='New Terms',\n        vat_reverse_charge_notes='New VAT Notes')","language":"python"},{"language":"xml","code":"<subscription>\n <terms_and_conditions>Payment can be sent to Acme Cloud, Inc.</terms_and_conditions>\n <customer_notes>Thanks for your business!</customer_notes>\n <vat_reverse_charge_notes>No VAT was applied on this invoice. Please reference this legislation.</vat_reverse_charge_notes>\n</subscription>"}]},"params":[{"_id":"55830d5281672a3900bb5032","required":false,"desc":"Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals, unless updated before renewal.","default":"","type":"string","name":"terms_and_conditions"},{"_id":"55830d5281672a3900bb5031","required":false,"desc":"Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"customer_notes"},{"_id":"55830d5281672a3900bb5030","required":false,"desc":"VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.","default":"","type":"string","name":"vat_reverse_charge_notes"}],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <terms_and_conditions>Payment can be sent to Acme Cloud, Inc.</terms_and_conditions>\n  <customer_notes>Thanks for your business!</customer_notes>\n  <vat_reverse_charge_notes>No VAT was applied on this invoice. Please reference this legislation.</vat_reverse_charge_notes>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <subscription_add_ons type=\"array\">\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/:uuid/notes"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T18:26:26.891Z","excerpt":"Update a subscription's invoice notes before the next renewal. Updating notes will not trigger the renewal.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":6,"project":"555fbba928249c1900618a82","slug":"update-subscription-notes","sync_unique":"","title":"Update Subscription Notes","type":"put","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Subscription Notes

Update a subscription's invoice notes before the next renewal. Updating notes will not trigger the renewal.

terms_and_conditions:
String
Optional notes field. This will default to the Terms and Conditions text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Terms and Conditions. Custom notes will stay with a subscription on all renewals, unless updated before renewal.
customer_notes:
String
Optional notes field. This will default to the Customer Notes text specified on the Invoice Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override Customer Notes. Custom notes will stay with a subscription on all renewals.
vat_reverse_charge_notes:
String
VAT Reverse Charge Notes only appear if you have EU VAT enabled or are using your own Avalara AvaTax account and the customer is in the EU, has a VAT number, and is in a different country than your own. This will default to the VAT Reverse Charge Notes text specified on the Tax Settings page in your Recurly admin, unless custom notes were created with the original subscription. Specify custom notes with this tag to add or override VAT Reverse Charge Notes. Custom notes will stay with a subscription on all renewals.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":1,"_id":"5595cb2cd4c23b0d00adf73a","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8c7aeb72f0257541b89405383ad69');\n  $subscription->unit_amount_in_cents = 1000;\n  $subscription->preview();\n  foreach ($subscription->invoice->line_items as $adjustment) {\n    print_r($adjustment);\n  }\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.unit_amount_in_cents = 1000\nsubscription.preview\nsubscrtption.invoice.line_items.each do |line_item|\n  puts line_item\nend"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.unit_amount_in_cents = 1000\nsubscription.preview()\n\nfor line_item in sub.invoice.line_items:\n    print line_item"},{"language":"xml","code":"<subscription>\n\t<unit_amount_in_cents>100</unit_amount_in_cents>\n</subscription>"}]},"params":[{"_id":"558312deea39a93900224360","required":true,"desc":"New unit amount in cents","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"558312deea39a93900224363","required":false,"desc":"Set as either \"now\" for immediate, \"renewal\" to perform when the subscription renews. defaults to \"now\" if not specified.","default":"now","type":"string","name":"timeframe"},{"_id":"558312deea39a93900224362","required":false,"desc":"New plan, remains unchanged if not specified.","default":"","type":"string","name":"plan_code"},{"_id":"558312deea39a93900224361","required":false,"desc":"New quantity, remains unchanged if not specified and the plan_code remains the same.","default":"","type":"int","name":"quantity"},{"_id":"558312deea39a9390022435f","required":false,"desc":"Optional field to set the collection for an invoice as \"automatic\" or \"manual\". The default is \"automatic\" if it's not set.","default":"","type":"string","name":"collection_method"},{"_id":"558312deea39a9390022435e","required":false,"desc":"Nested add-on information for the subscription, the new subscription will have no add-ons unless specified.","default":"","type":"object","name":"subscription_add_ons"}],"results":{"codes":[{"name":"","code":"<subscription href=\"\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n  <address>\n      <address1>123 Main St</address1>\n      <address2></address2>\n      <city>San Francisco</city>\n      <state>CA</state>\n      <zip>12345</zip>\n      <country>US</country>\n      <phone></phone>\n  </address>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>pending</state>\n  <cost_in_cents>3379</cost_in_cents>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>USD</currency>\n  <quantity type=\"integer\">2</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">279</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.09</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <collection_method>automatic</collection_method>\n  <subscription_add_ons type=\"array\">\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n  <invoice>\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\" />\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\" />\n    <uuid>421f7b7d414e4c6792938e7c49d552e9</uuid>\n    <state>open</state>\n    <invoice_number nil=\"nil\"><invoice_number>\n    <po_number nil=\"nil\"></po_number>\n    <vat_number nil=\"nil\"></vat_number>\n    <subtotal_in_cents type=\"integer\">9900</subtotal_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <total_in_cents type=\"integer\">9900</total_in_cents>\n    <currency>USD</currency>\n    <created_at type=\"datetime\">2011-08-25T12:00:00Z</created_at>\n    <closed_at nil=\"nil\"></closed_at>\n    <tax_type>usst</tax_type>\n    <tax_region>CA</tax_region>\n    <tax_rate type=\"float\">0.09</tax_rate>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <redemption href=\"https://your-subdomain.recurly.com/v2/invoices/e3f0a9e084a2468480d00ee61b090d4d/redemption\"/>\n    <line_items type=\"array\">\n      <adjustment>\n        <!-- Detail. Includes proration amounts if applicable -->\n      </adjustment>\n    </line_items>\n    <transactions nil=\"nil\"></transactions>\n  </invoice>\n</subscription>","language":"xml","status":201}]},"settings":"","url":"/subscriptions/:uuid/preview"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T18:50:06.036Z","excerpt":"Returns a preview for a subscription change applied to an account without committing a subscription change or posting an invoice.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":7,"project":"555fbba928249c1900618a82","slug":"preview-subscription-change","sync_unique":"","title":"Preview Subscription Change","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postPreview Subscription Change

Returns a preview for a subscription change applied to an account without committing a subscription change or posting an invoice.

unit_amount_in_cents:
required
Integer
New unit amount in cents
timeframe:
Stringnow
Set as either "now" for immediate, "renewal" to perform when the subscription renews. defaults to "now" if not specified.
plan_code:
String
New plan, remains unchanged if not specified.
quantity:
Integer
New quantity, remains unchanged if not specified and the plan_code remains the same.
collection_method:
String
Optional field to set the collection for an invoice as "automatic" or "manual". The default is "automatic" if it's not set.
subscription_add_ons:
Object
Nested add-on information for the subscription, the new subscription will have no add-ons unless specified.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":5,"_id":"5595cb2cd4c23b0d00adf73b","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');\n  $subscription->cancel();\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n} catch (Recurly_Error $e) {\n  print \"Subscription already canceled: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.cancel"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.cancel()"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.Cancel();"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>cancelled</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\">2011-05-27T07:00:00Z</canceled_at>\n  <expires_at nil=\"nil\">2011-07-27T07:00:00Z</expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2011-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n  <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/:uuid/cancel"},"body":"Canceling a subscription turns off the subscription's auto-renewal. The subscription will continue through the current, invoiced term. When the subscription is up for renewal, the account will transition to a free account and the subscription will no longer be active.\n\nWhen a subscription is canceled, Recurly will send a cancelation webhook. Recurly will send an additional subscription expired webhook once the subscription is no longer active.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Please note: If a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:02:33.781Z","excerpt":"Cancel a subscription so it remains active and then expires at the end of the current bill cycle.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":8,"project":"555fbba928249c1900618a82","slug":"cancel-subscription","sync_unique":"","title":"Cancel Subscription","type":"put","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putCancel Subscription

Cancel a subscription so it remains active and then expires at the end of the current bill cycle.

Canceling a subscription turns off the subscription's auto-renewal. The subscription will continue through the current, invoiced term. When the subscription is up for renewal, the account will transition to a free account and the subscription will no longer be active. When a subscription is canceled, Recurly will send a cancelation webhook. Recurly will send an additional subscription expired webhook once the subscription is no longer active. [block:callout] { "type": "warning", "body": "Please note: If a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Canceling a subscription turns off the subscription's auto-renewal. The subscription will continue through the current, invoiced term. When the subscription is up for renewal, the account will transition to a free account and the subscription will no longer be active. When a subscription is canceled, Recurly will send a cancelation webhook. Recurly will send an additional subscription expired webhook once the subscription is no longer active. [block:callout] { "type": "warning", "body": "Please note: If a subscription that is set to start in the future is canceled, the subscription will be deleted from the account and will not show up in the account's subscription list." } [/block]
{"__v":3,"_id":"5595cb2cd4c23b0d00adf73c","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8c7aeb72f0257541b89405383ad69');\n  $subscription->reactivate();\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n} catch (Recurly_Error $e) {\n  print \"Subscription already reactivated: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.reactivate"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.reactivate()"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.Reactivate();"}]},"params":[],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n  <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n</subscription>"}]},"settings":"","url":"/subscriptions/:uuid/reactivate"},"body":"When a subscription is canceled, it will not renew. It is considered active until the end of the current billing period. Then, the subscription will end. To renew the subscription without modifying it, simply send a reactivation request to this end point.","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:08:37.097Z","excerpt":"Reactivate a canceled subscription so it renews at the end of the current bill cycle.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":9,"project":"555fbba928249c1900618a82","slug":"reactivate-canceled-subscription","sync_unique":"","title":"Reactivate Canceled Subscription","type":"put","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putReactivate Canceled Subscription

Reactivate a canceled subscription so it renews at the end of the current bill cycle.

When a subscription is canceled, it will not renew. It is considered active until the end of the current billing period. Then, the subscription will end. To renew the subscription without modifying it, simply send a reactivation request to this end point.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



When a subscription is canceled, it will not renew. It is considered active until the end of the current billing period. Then, the subscription will end. To renew the subscription without modifying it, simply send a reactivation request to this end point.
{"__v":1,"_id":"5595cb2cd4c23b0d00adf73d","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8c7aeb72f0257541b89405383ad69');\n  $subscription->terminateWithoutRefund();\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n} catch (Recurly_Error $e) {\n  print \"Subscription already terminated: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.terminate :partial"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.terminate(refund='partial')"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.Terminate(Subscription.RefundType.Full);\n//subscription.Terminate(Subscription.RefundType.Partial);\n//subscription.Terminate(Subscription.RefundType.None);"}]},"params":[{"_id":"55831ac3870ff41900de47a8","required":false,"desc":"'partial', 'full', or 'none' refund processed on the subscription charges","default":"none","type":"string","name":"refund_type"}],"results":{"codes":[{"name":"","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>expired</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\">2011-05-27T07:00:00Z</canceled_at>\n  <expires_at nil=\"nil\">2011-05-27T07:00:00Z</expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2011-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n  <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n</subscription>","language":"xml","status":200}]},"settings":"","url":"/subscriptions/:uuid/terminate?refund=:refund_type"},"body":"[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Refund Type\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"partial\",\n    \"0-1\": \"Prorates a refund based on the amount of time remaining in the current bill cycle.\",\n    \"1-0\": \"full\",\n    \"1-1\": \"Performs a full refund of the last charge for the current subscription term.\",\n    \"2-0\": \"none\",\n    \"2-1\": \"Terminates the subscription without a refund.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:23:47.144Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":10,"project":"555fbba928249c1900618a82","slug":"terminate-subscription","sync_unique":"","title":"Terminate Subscription","type":"put","updates":["55b6f7996de28c0d00406369"],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putTerminate Subscription


refund_type:
Stringnone
'partial', 'full', or 'none' refund processed on the subscription charges
[block:parameters] { "data": { "h-0": "Refund Type", "h-1": "Description", "0-0": "partial", "0-1": "Prorates a refund based on the amount of time remaining in the current bill cycle.", "1-0": "full", "1-1": "Performs a full refund of the last charge for the current subscription term.", "2-0": "none", "2-1": "Terminates the subscription without a refund." }, "cols": 2, "rows": 3 } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:parameters] { "data": { "h-0": "Refund Type", "h-1": "Description", "0-0": "partial", "0-1": "Prorates a refund based on the amount of time remaining in the current bill cycle.", "1-0": "full", "1-1": "Performs a full refund of the last charge for the current subscription term.", "2-0": "none", "2-1": "Terminates the subscription without a refund." }, "cols": 2, "rows": 3 } [/block]
{"__v":5,"_id":"5595cb2cd4c23b0d00adf73e","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('2fe8fc16788daa5b9cca4d4df99c9ac7');\n  $subscription->postpone(date('c', strtotime('2016-12-31Z')), False);\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.postpone Time.utc(2012, 12, 31), false"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.postpone(next_renewal_date=datetime.datetime(2012, 12, 31), False)"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.Postpone(new DateTime(2012, 12, 31), false);"}]},"params":[],"results":{"codes":[{"name":"","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2012-12-31T00:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <tax_in_cents type=\"integer\">80</tax_in_cents>\n  <tax_type>usst</tax_type>\n  <tax_region>CA</tax_region>\n  <tax_rate type=\"float\">0.0875</tax_rate>\n  <po_number nil=\"nil\"></po_number>\n  <net_terms type=\"integer\">0</net_terms>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n  <a name=\"postpone\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/postpone\" method=\"put\"/>\n</subscription>","language":"xml","status":200}]},"settings":"","url":"/subscriptions/:uuid/postpone?next_renewal_date=:next_renewal_date&bulk=:bulk"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:26:20.104Z","excerpt":"For an active subscription, this will pause the subscription until the specified date. The subscription will not be prorated. For a subscription in a trial period, modifying the renewal date will modify when the trial expires.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":11,"project":"555fbba928249c1900618a82","slug":"postpone-subscription","sync_unique":"","title":"Postpone Subscription","type":"put","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

putPostpone Subscription

For an active subscription, this will pause the subscription until the specified date. The subscription will not be prorated. For a subscription in a trial period, modifying the renewal date will modify when the trial expires.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf73f","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = new Recurly_Subscription();\n  $subscription->plan_code = 'gold';\n  $subscription->currency = 'EUR';\n\n  $account = new Recurly_Account();\n  $account->account_code = 'b6f5783';\n  $account->email = 'verena@example.com';\n  $account->first_name = 'Verena';\n  $account->last_name = 'Example';\n\n  $billing_info = new Recurly_BillingInfo();\n  $billing_info->number = '4111-1111-1111-1111';\n  $billing_info->month = 12;\n  $billing_info->year = 2017;\n  $billing_info->verification_value = 123;\n  $billing_info->address1 = '400 Alabama St';\n  $billing_info->city = 'San Francisco';\n  $billing_info->state = 'CA';\n  $billing_info->country = 'US';\n  $billing_info->zip = '94110';\n\n  $account->billing_info = $billing_info;\n  $subscription->account = $account;\n\n  // Existing Addon\n  $addon1 = new Recurly_SubscriptionAddOn();\n  $addon1->add_on_code = 'extra_users';\n  $addon1->quantity = 2;\n  $addon1->unit_amount_in_cents = 1000;\n\n  // Existing Addon\n  $addon2 = new Recurly_SubscriptionAddOn();\n  $addon2->add_on_code = 'extra_ips';\n  $addon2->quantity = 3;\n  $addon2->unit_amount_in_cents = 100;\n\n  $subscription->subscription_add_ons = array($addon1, $addon2);\n\n  $subscription->create();\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Plan, Subscription, Account, Addon, or BillingInfo data: $e\";\n}","name":""},{"language":"ruby","code":"addon1 = Recurly::SubscriptionAddOn.new('extra_users')\naddon1.quantity = 2\n\naddon2 = Recurly::SubscriptionAddOn.new('extra_ips')\naddon2.quantity = 3\n\nsubscription = Recurly::Subscription.create(\n  :plan_code => 'gold',\n  :currency  => 'EUR',\n  :subscription_add_ons => [\n  \taddon1,\n  \taddon2\n  ],\n  :account   => {\n    :account_code => '1',\n    :email        => 'verena@example.com',\n    :first_name   => 'Verena',\n    :last_name    => 'Example',\n    :billing_info => {\n      :number => '4111-1111-1111-1111',\n      :month  => 1,\n      :year   => 2014,\n    }\n  }\n)"},{"language":"python","code":"subscription = Subscription()\nsubscription.plan_code = 'gold'\nsubscription.currency = 'EUR'\n\naccount = Account(account_code='1')\naccount.email = 'verena@example.com'\naccount.first_name = 'Verena'\naccount.last_name = 'Example'\n\nbilling_info = BillingInfo()\nbilling_info.number = '4111-1111-1111-1111'\nbilling_info.month = 1\nbilling_info.year = 2014\n\naccount.billing_info = billing_info\nsubscription.account = account\n\naddon1 = SubscriptionAddOn()\naddon1.add_on_code = 'extra_users'\naddon1.quantity = 2\n\naddon2 = SubscriptionAddOn()\naddon2.add_on_code = 'extra_ips'\naddon2.quantity = 3\n\nsubscription.subscription_add_ons = [addon1, addon2]\n\nsubscription.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar plan = Plans.Get(\"gold\");\nvar subscription = new Subscription(account, plan, \"USD\"); // account, plan, currency\nsubscription.AddOns.Add(\"extra_users\", 2);\nsubscription.AddOns.Add(plan.GetAddOn(\"extra_ips\", 3));\nsubscription.Create();"},{"language":"xml","code":"<subscription>\n  <plan_code>gold</plan_code>\n  <currency>EUR</currency>\n  <subscription_add_ons>\n    <subscription_add_on>\n      <add_on_code>extra_users</add_on_code>\n      <quantity>2</quantity>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n    </subscription_add_on>\n    <subscription_add_on>\n      <add_on_code>extra_ip</add_on_code>\n      <quantity>3</quantity>\n      <unit_amount_in_cents>200</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n  <account>\n    <account_code>1</account_code>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <billing_info>\n      <number>4111-1111-1111-1111</number>\n      <month>1</month>\n      <year>2014</year>\n    </billing_info>\n  </account>\n</subscription>"}]},"params":[{"_id":"55833b1181672a3900bb5117","required":true,"desc":"The code for the Add-On.","default":"","type":"string","name":"add_on_code"},{"_id":"55833b1181672a3900bb5116","required":false,"desc":"Amount of the transaction in cents. Max 10000000.","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"55833b1181672a3900bb5115","required":false,"desc":"Optionally override the default quantity of 1","default":"","type":"int","name":"quantity"}],"results":{"codes":[{"status":201,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <subscription_add_ons type=\"array\">\n    <subscription_add_on>\n      <add_on_code>extra_users</add_on_code>\n      <quantity>2</quantity>\n      <unit_amount_in_cents>1000</unit_amount_in_cents>\n    </subscription_add_on>\n    <subscription_add_on>\n      <add_on_code>extra_ip</add_on_code>\n      <quantity>3</quantity>\n      <unit_amount_in_cents>200</unit_amount_in_cents>\n    </subscription_add_on>\n   </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions"},"body":"For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://dash.readme.io/project/recurly/v2.0/docs/create-subscription)","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:27:16.499Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":12,"project":"555fbba928249c1900618a82","slug":"subscription-add-ons","sync_unique":"","title":"Create a Subscription with Add-Ons","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postCreate a Subscription with Add-Ons


add_on_code:
required
String
The code for the Add-On.
unit_amount_in_cents:
Integer
Amount of the transaction in cents. Max 10000000.
quantity:
Integer
Optionally override the default quantity of 1
For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://dash.readme.io/project/recurly/v2.0/docs/create-subscription)

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://dash.readme.io/project/recurly/v2.0/docs/create-subscription)
{"__v":0,"_id":"5595cb2cd4c23b0d00adf741","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');\n\n  /* Add one add-on */\n\n  $newaddon = new Recurly_SubscriptionAddOn();\n  $newaddon->add_on_code = 'my-new-add-on'; // Existing addon code\n  $newaddon->quantity = 2;\n  $newaddon->unit_amount_in_cents = 1000;\n\n  $subscription->subscription_add_ons[] = $newaddon;\n\n  /* Adjust the quantity of one add-on */\n\n  $updateaddon = $subscription->subscription_add_ons[1];\n  $updateaddon->quantity++;\n  $subscription->subscription_add_ons[1] = $updateaddon;\n\n  /* Remove one add-on */\n\n  unset($subscription->subscription_add_ons[1]);\n\n  /* Remove all add-ons */\n\n  $subscription->subscription_add_ons = array();\n\n  /* Call for update */\n\n  $subscription->updateImmediately();     // Update immediately.\n  // or $subscription->updateAtRenewal(); // Update when the subscription renews.\n\n  print \"Subscription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Subscription or Addon data: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\n\n#\n#Add one add-on\n#\n\nnewaddon = Recurly::SubscriptionAddOn.new('my-new-add-on')\nnewaddon.quantity = 2\n\nsubscription.subscription_add_ons = subscription.subscription_add_ons + [ newaddon ]\n\n#\n#Adjust the quantity of one add-on\n#\n\n#create the updated add-on\naddon1 = Recurly::SubscriptionAddOn.new('my-new-add-on')\naddon1.quantity = 6\nsubscription = Recurly::Subscription.find('21339738efb441c3163f644c169a0849')\n\n#remove the add-on from the list\nsubscription.subscription_add_ons = subscription.subscription_add_ons.reject {|add_on| add_on.add_on_code == 'my-new-add-on'}\n\n#add the updated add-on\nsubscription.subscription_add_ons = subscription.subscription_add_ons + [addon1]\n\n#\n#Remove one add-on\n#\n\nsubscription.subscription_add_ons = subscription.subscription_add_ons.reject {|add_on| add_on.add_on_code == 'my-new-add-on'}\n\n#\n#Remove all add-ons\n#\n\nsubscription.subscription_add_ons = []\n\n#\n#Call for update\n#\n\nsubscription.update_attributes(\n  :timeframe => 'now'\n)"},{"language":"python","code":"subscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\n\n#\n#Add one add-on\n#\n\nnewaddon = SubscriptionAddOn()\nnewaddon.add_on_code = 'my-new-add-on'\nnewaddon.quantity = 2\nadd_ons = subscription.subscription_add_ons\n\n#need to copy old add-ons\nsubscription.subscription_add_ons = []\nfor a in add_ons:\n    tempaddon = SubscriptionAddOn()\n    tempaddon.add_on_code = a.add_on_code\n    tempaddon.quantity = a.quantity\n    tempaddon.unit_amount_in_cents = a.unit_amount_in_cents\n    subscription.subscription_add_ons.append(tempaddon)\n\n#append new add-on    \nsubscription.subscription_add_ons.append(newaddon)\n\n#\n#Adjust the quantity of one add-on \n#\n\n#need to copy old add-ons\nadd_ons = subscription.subscription_add_ons\nsubscription.subscription_add_ons = []\nfor a in add_ons:\n    tempaddon = SubscriptionAddOn()\n    tempaddon.add_on_code = a.add_on_code\n    tempaddon.quantity = a.quantity\n    #check for a specific add-on\n    if tempaddon.add_on_code == 'my-new-add-on':\n        tempaddon.quantity = 6\n    tempaddon.unit_amount_in_cents = a.unit_amount_in_cents\n    subscription.subscription_add_ons.append(tempaddon)\n\n#\n#Remove one add-on\n#\n\nadd_ons = subscription.subscription_add_ons\nsubscription.subscription_add_ons = []\nfor a in add_ons:\n    if a.add_on_code != 'my-new-add-on':\n        tempaddon = SubscriptionAddOn()\n        tempaddon.add_on_code = a.add_on_code\n        tempaddon.quantity = a.quantity\n        tempaddon.unit_amount_in_cents = a.unit_amount_in_cents\n        subscription.subscription_add_ons.append(tempaddon)\n\n#\n#Remove All Add-ons\n#\n\nsubscription.subscription_add_ons = []\n\n\n#\n#Call for update\n#\n\nsubscription.timeframe = 'now'       # Update immediately.\n# subscription.timeframe = 'renewal' # Update when the subscription renews.\nsubscription.save()"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\n\n// append a new add-on\nvar addOn = plan.GetAddOn(\"my_new_add_on\");\nsubscription.AddOns.Add(addOn);\n\n// change a quantity of an existing add-on\nvar existingAddOn = subscription.AddOns.AsQueryable().First(x => x.AddOnCode == \"extra_ips\");\nexistingAddOn.Quantity = 6;\n\n// remove an add-on\nsubscription.AddOns.RemoveAt(0);\n\n// remove all add-ons\nsubscription.AddOns.Clear();\n\n// call for an update\nsubscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);"},{"language":"xml","code":"Accept: application/xml\nContent-Type: application/xml; charset=utf-8\n<subscription>\n  <timeframe>now</timeframe>\n  <quantity>2</quantity>\n  <subscription_add_ons>\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n</subscription>"}]},"params":[{"_id":"55833c9d870ff41900de485d","required":true,"desc":"The code for the Add-On.","default":"","type":"string","name":"add_on_code"},{"_id":"55833c9d870ff41900de485c","required":false,"desc":"Amount of the transaction in cents. Max 10000000.","default":"","type":"int","name":"unit_amount_in_cents"},{"_id":"55833c9d870ff41900de485b","required":false,"desc":"Optionally override the default quantity of 1","default":"","type":"int","name":"quantity"}],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <current_period_started_at type=\"datetime\">2011-06-27T07:00:00Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2010-07-27T07:00:00Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <subscription_add_ons type=\"array\">\n    <subscription_add_on>\n      <add_on_code>ipaddresses</add_on_code>\n      <quantity>10</quantity>\n      <unit_amount_in_cents>150</unit_amount_in_cents>\n    </subscription_add_on>\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/:uuid"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T21:48:13.952Z","excerpt":"The original subscription’s add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":13,"project":"555fbba928249c1900618a82","slug":"update-subscription-with-add-ons","sync_unique":"","title":"Update Subscription with Add-Ons","type":"put","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Subscription with Add-Ons

The original subscription’s add-ons will be removed unless they are specified in your update subscription request. Please specify all the add-ons that should be present after the subscription change.

add_on_code:
required
String
The code for the Add-On.
unit_amount_in_cents:
Integer
Amount of the transaction in cents. Max 10000000.
quantity:
Integer
Optionally override the default quantity of 1

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2cd4c23b0d00adf740","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = new Recurly_Subscription();\n  $subscription->plan_code = 'silver';\n  $subscription->currency = 'EUR';\n  $subscription->collection_method = 'manual';\n  $subscription->net_terms = 10;\n  $subscription->po_number = 'PO2934';\n\n  $account = new Recurly_Account();\n  $account->account_code = 'b6f5783';\n\n  $subscription->account = $account;\n\n  $subscription->create();\n\n  print \"Subcription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Subscription or Account data: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.create(\n  :plan_code => 'gold',\n  :currency  => 'EUR',\n  :collection_method  => 'manual',\n  :net_terms  => 10,\n  :po_number  => 'PO12678',\n  :account   => {\n    :account_code => '1',\n  }\n)"},{"language":"python","code":"subscription = Subscription()\nsubscription.plan_code = 'gold'\nsubscription.currency = 'EUR'\nsubscription.collection_method = 'manual'\nsubscription.net_terms = 10\nsubscription.po_number = 'PO1234'\n\naccount = Account(account_code='1')\n\nsubscription.account = account\n\nsubscription.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\nvar plan = Plans.Get(\"gold\");\nvar subscription = new Subscription(account, plan, \"USD\"); // account, plan, currency\nsubscription.CollectionMethod = \"manual\";\nsubscription.NetTerms = 10;\nsubscription.PoNumber = \"PO1234\";\nsubscription.Create();"},{"language":"xml","code":"<subscription>\n  <plan_code>gold</plan_code>\n  <currency>EUR</currency>\n  <collection_method>manual</collection_method>\n  <net_terms>10</net_terms>\n  <po_number>PO19384</po_number>\n  <account>\n    <account_code>1</account_code>\n  </account>\n</subscription>"}]},"params":[{"_id":"55833d22ea39a939002244d1","required":false,"desc":"Can be either 'automatic' or 'manual'. Defaults to 'automatic'.","default":"","type":"string","name":"collection_method"},{"_id":"55833d22ea39a939002244d0","required":false,"desc":"A number, 0 for On Receipt.","default":"","type":"string","name":"net_terms"},{"_id":"55833d22ea39a939002244cf","required":false,"desc":"Optionally attach a PO number to the subscription","default":"","type":"string","name":"po_number"}],"results":{"codes":[{"name":"","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <total_billing_cycles nil=\"nil\"></total_billing_cycles>\n  <remaining_billing_cycles nil=\"nil\"></remaining_billing_cycles>\n  <current_period_started_at type=\"datetime\">2013-07-11T16:12:16Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2013-08-11T16:12:16Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <po_number>PO19384</po_number>\n  <net_terms type=\"integer\">10</net_terms>\n  <collection_method>manual</collection_method>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","language":"xml","status":201}]},"settings":"","url":"/subscriptions"},"body":"For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://recurly.readme.io/v2.0/docs/subscriptions)\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Since manual invoicing is a new feature, please make sure you have the most up-to-date client library code.\"\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T19:35:05.221Z","excerpt":"Creating a subscription with a manual collection method allows you to accept payment from outside of Recurly.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":14,"project":"555fbba928249c1900618a82","slug":"subscriptions-for-manual-invoicing","sync_unique":"","title":"Create Subscription (Manual Invoice)","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postCreate Subscription (Manual Invoice)

Creating a subscription with a manual collection method allows you to accept payment from outside of Recurly.

collection_method:
String
Can be either 'automatic' or 'manual'. Defaults to 'automatic'.
net_terms:
String
A number, 0 for On Receipt.
po_number:
String
Optionally attach a PO number to the subscription
For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://recurly.readme.io/v2.0/docs/subscriptions) [block:callout] { "type": "warning", "body": "Since manual invoicing is a new feature, please make sure you have the most up-to-date client library code." } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



For a full list of subscription parameters, see the full subscriptions endpoint documentation [here](https://recurly.readme.io/v2.0/docs/subscriptions) [block:callout] { "type": "warning", "body": "Since manual invoicing is a new feature, please make sure you have the most up-to-date client library code." } [/block]
{"__v":0,"_id":"5595cb2cd4c23b0d00adf742","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $subscription = Recurly_Subscription::get('44f83d7cba354d5b84812419f923ea96');\n  $subscription->collection_method = 'manual';\n  $subscription->net_terms = 10;\n  $subscription->po_number = 'PO1837';\n  $subscription->updateImmediately();     // Update immediately.\n  // or $subscription->updateAtRenewal(); // Update when the subscription renews.\n\n  print \"Subcription: $subscription\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid Subscription or Account data: $e\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Subscription Not Found: $e\";\n}","name":""},{"language":"ruby","code":"subscription = Recurly::Subscription.find('44f83d7cba354d5b84812419f923ea96')\nsubscription.update_attributes(\n  :collection_method => 'silver',\n  :net_terms  => 2,\n  :po_number => 'PO2184',\n  :timeframe => 'now'       # Update immediately.\n  # :timeframe => 'renewal' # Update when the subscription renews.\n)"},{"language":"python","code":"#need python library version >= 2.1.11\n\nsubscription = Subscription.get('44f83d7cba354d5b84812419f923ea96')\nsubscription.collection_method = 'manual'\nsubscription.net_terms = 10\nsubscription.po_number = 'PO2894'\nsubscription.timeframe = 'now'       # Update immediately.\n# subscription.timeframe = 'renewal' # Update when the subscription renews.\nsubscription.save()"},{"language":"csharp","code":"var subscription = Subscriptions.Get(\"44f83d7cba354d5b84812419f923ea96\");\nsubscription.CollectionMethod = \"manual\";\nsubscription.NetTerms = 10;\nsubscription.PoNumber = \"PO1234\";\nsubscription.ChangeSubscription(Subscription.ChangeTimeframe.Now);"},{"language":"xml","code":"Accept: application/xml\nContent-Type: application/xml; charset=utf-8\n<subscription>\n  <timeframe>now</timeframe>\n  <collection_method>manual</collection_method>\n  <net_terms>manual</net_terms>\n  <po_number>manual</po_number>\n</subscription>"}]},"params":[{"_id":"55833e14ea39a939002244d6","required":false,"desc":"Can be either 'automatic' or 'manual'.","default":"automatic","type":"string","name":"collection_method"},{"_id":"55833e14ea39a939002244d5","required":false,"desc":"A number, 0 for On Receipt.","default":"","type":"int","name":"net_terms"},{"_id":"55833e14ea39a939002244d4","required":false,"desc":"Optionally attach a PO number to the subscription","default":"","type":"string","name":"po_number"}],"results":{"codes":[{"status":200,"language":"xml","code":"<subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/gold\">\n    <plan_code>gold</plan_code>\n    <name>Gold plan</name>\n  </plan>\n  <uuid>44f83d7cba354d5b84812419f923ea96</uuid>\n  <state>active</state>\n  <unit_amount_in_cents type=\"integer\">800</unit_amount_in_cents>\n  <currency>EUR</currency>\n  <quantity type=\"integer\">1</quantity>\n  <activated_at type=\"datetime\">2011-05-27T07:00:00Z</activated_at>\n  <canceled_at nil=\"nil\"></canceled_at>\n  <expires_at nil=\"nil\"></expires_at>\n  <total_billing_cycles nil=\"nil\"></total_billing_cycles>\n  <remaining_billing_cycles nil=\"nil\"></remaining_billing_cycles>\n  <current_period_started_at type=\"datetime\">2013-07-11T16:12:16Z</current_period_started_at>\n  <current_period_ends_at type=\"datetime\">2013-08-11T16:12:16Z</current_period_ends_at>\n  <trial_started_at nil=\"nil\"></trial_started_at>\n  <trial_ends_at nil=\"nil\"></trial_ends_at>\n  <po_number>PO19384</po_number>\n  <net_terms type=\"integer\">10</net_terms>\n  <collection_method>manual</collection_method>\n  <subscription_add_ons type=\"array\">\n  </subscription_add_ons>\n  <a name=\"cancel\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/cancel\" method=\"put\"/>\n  <a name=\"terminate\" href=\"https://your-subdomain.recurly.com/v2/subscriptions/44f83d7cba354d5b84812419f923ea96/terminate\" method=\"put\"/>\n</subscription>","name":""}]},"settings":"","url":"/subscriptions/:uuid"},"body":"","category":"5595cb2ad4c23b0d00adf6eb","createdAt":"2015-06-18T21:54:28.954Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":15,"project":"555fbba928249c1900618a82","slug":"update-subscription-manual-invoice","sync_unique":"","title":"Update Subscription (Manual Invoice)","type":"put","updates":[],"user":"55648cf93b87582b003ab8b1","version":"5595cb29d4c23b0d00adf6e3"}

putUpdate Subscription (Manual Invoice)


collection_method:
Stringautomatic
Can be either 'automatic' or 'manual'.
net_terms:
Integer
A number, 0 for On Receipt.
po_number:
String
Optionally attach a PO number to the subscription

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf700","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$transactions = Recurly_TransactionList::get();\nforeach ($transactions as $transaction) {\n  print \"Transaction: $transaction\\n\";\n}","name":""},{"language":"ruby","code":"Recurly::Transaction.find_each do |transaction|\n  puts \"Transaction: #{transaction.inspect}\"\nend"},{"language":"python","code":"#client version 2.1.6+\nfor transaction in Transaction.all():\n    print 'Transaction: %s' % transaction\n\n#client version <= 2.1.5\ntransactions = Transaction.all()\nwhile transactions:\n    for transaction in transactions:\n        print 'Transaction: %s' % transaction\n    try:\n        transactions = transactions.next_page()\n    except PageError:\n        transactions = ()"},{"language":"csharp","code":"using System.Linq;\n\nvar transactions = Transactions.List();\nwhile (transactions.Any())\n{\n\tforeach (var transaction in transactions)\n\t\tConsole.WriteLine(\"Transaction: \" + transaction);\n\ttransactions = transactions.Next;\n}\n\n// Filter successful Transactions\nvar transactions = Transactions.List(TransactionList.TransactionState.Success);\n\n// Filter failed purchases\nvar transactions = Transactions.List(TransactionList.TransactionState.Success,\n                                     TransactionList.TransactionType.Failed);"}]},"params":[{"_id":"5581f9d1a5474a0d00d94727","required":false,"desc":"The state of transactions to return: \"successful\", \"failed\", or \"voided\".","default":"","type":"string","name":"state"},{"_id":"5581f9d1a5474a0d00d94726","required":false,"desc":"The type of transactions to return: \"authorization\", \"refund\", or \"purchase\".","default":"","type":"string","name":"type"},{"_id":"5581f9d1a5474a0d00d94725","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"5581f9d1a5474a0d00d94724","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"string","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<transactions type=\"array\">\n  <transaction href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" type=\"credit_card\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>\n    <action>purchase</action>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <currency>USD</currency>\n    <status>success</status>\n    <payment_method>credit_card</payment_method>\n    <reference>5416477</reference>\n    <source>subscription</source>\n    <recurring type=\"boolean\">true</recurring>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n    <ip_address>127.0.0.1</ip_address>\n    <cvv_result code=\"M\">Match</cvv_result>\n    <avs_result code=\"D\">Street address and postal code match.</avs_result>\n    <avs_result_street nil=\"nil\"/>\n    <avs_result_postal nil=\"nil\"/>\n    <created_at type=\"datetime\">2015-06-10T15:25:06Z</created_at>\n    <details>\n      <account>\n        <account_code>1</account_code>\n        <first_name>Verena</first_name>\n        <last_name>Example</last_name>\n        <company nil=\"nil\"/>\n        <email>verena@test.com</email>\n        <billing_info type=\"credit_card\">\n          <first_name>Verena</first_name>\n          <last_name>Example</last_name>\n          <address1>123 Main St.</address1>\n          <address2 nil=\"nil\"/>\n          <city>San Francisco</city>\n          <state>CA</state>\n          <zip>94105</zip>\n          <country>US</country>\n          <phone nil=\"nil\"/>\n          <vat_number nil=\"nil\"/>\n          <card_type>Visa</card_type>\n          <year type=\"integer\">2017</year>\n          <month type=\"integer\">11</month>\n          <first_six>411111</first_six>\n          <last_four>1111</last_four>\n        </billing_info>\n      </account>\n    </details>\n    <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" method=\"delete\"/>\n  </transaction>\n  <!-- Continued... -->\n</transactions>","name":""}]},"settings":"","url":"/transactions"},"body":"","category":"5595cb2ad4c23b0d00adf6ea","createdAt":"2015-06-17T22:35:55.612Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"555fbba928249c1900618a82","slug":"list-transactions","sync_unique":"","title":"List Transactions","type":"get","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getList Transactions


state:
String
The state of transactions to return: "successful", "failed", or "voided".
type:
String
The type of transactions to return: "authorization", "refund", or "purchase".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
String50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":0,"_id":"5595cb2bd4c23b0d00adf701","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"try {\n  $transactions = Recurly_TransactionList::getForAccount('b6f5783');\n  foreach ($transactions as $transaction) {\n    print \"Transaction: $transaction\\n\";\n  }\n} catch (Recurly_NotFoundError $e) {\n  print \"Account Not Found: $e\";\n}","name":""},{"language":"ruby","code":"account = Recurly::Account.find('1')\naccount.transactions.find_each do |transaction|\n  puts \"Transaction: #{transaction.inspect}\"\nend"},{"name":null,"language":"python","code":"#client version 2.1.6+\naccount = Account.get('1')\nfor transaction in account.transactions():\n    print 'Transaction: %s' % transaction\n\n#client version <= 2.1.5\naccount = Account.get('1')\ntransactions = account.transactions()\nwhile transactions:\n    for transaction in transactions:\n        print 'Transaction: %s' % transaction\n    try:\n        transactions = transactions.next_page()\n    except PageError:\n        transactions = ()"},{"language":"csharp","code":"using System.Linq;\n\nvar account = Accounts.Get(\"1\");\nvar transactions = account.GetTransactions();\nwhile (transactions.Any())\n{\n\tforeach (var transaction in transactions)\n\t\tConsole.WriteLine(\"Transaction: \" + transaction);\n\ttransactions = transactions.Next;\n}"}]},"params":[{"_id":"5581fc16a5474a0d00d94735","required":false,"desc":"The state of transactions to return: \"successful\", \"failed\", or \"voided\".","default":"","type":"string","name":"state"},{"_id":"5581fc16a5474a0d00d94734","required":false,"desc":"The type of transactions to return: \"authorization\", \"refund\", or \"purchase\".","default":"","type":"string","name":"type"},{"_id":"5581fc16a5474a0d00d94733","required":false,"desc":"Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.","default":"","type":"string","name":"cursor"},{"_id":"5581fc16a5474a0d00d94732","required":false,"desc":"Number of records to return per page, up to a maximum of 200.","default":"50","type":"string","name":"per_page"}],"results":{"codes":[{"status":200,"language":"xml","code":"<transactions type=\"array\">\n  <transaction href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" type=\"credit_card\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n    <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n    <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>\n    <action>purchase</action>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <tax_in_cents type=\"integer\">0</tax_in_cents>\n    <currency>USD</currency>\n    <status>success</status>\n    <payment_method>credit_card</payment_method>\n    <reference nil=\"nil\"></reference>\n    <source>subscription</source>\n    <recurring type=\"boolean\">false</recurring>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n    <ip_address>127.0.0.1</ip_address>\n    <cvv_result code=\"\" nil=\"nil\"></cvv_result>\n    <avs_result code=\"\" nil=\"nil\"></avs_result>\n    <avs_result_street nil=\"nil\"></avs_result_street>\n    <avs_result_postal nil=\"nil\"></avs_result_postal>\n    <created_at type=\"datetime\">2011-06-27T12:34:56Z</created_at>\n    <details>\n      <account>\n        <account_code>verena100</account_code>\n        <first_name>Verena</first_name>\n        <last_name>Example</last_name>\n        <company nil=\"nil\"></company>\n        <email>verena@test.com</email>\n        <billing_info type=\"credit_card\">\n          <first_name nil=\"nil\"></first_name>\n          <last_name nil=\"nil\"></last_name>\n          <address1 nil=\"nil\"></address1>\n          <address2 nil=\"nil\"></address2>\n          <city nil=\"nil\"></city>\n          <state nil=\"nil\"></state>\n          <zip nil=\"nil\"></zip>\n          <country nil=\"nil\"></country>\n          <phone nil=\"nil\"></phone>\n          <vat_number nil=\"nil\"></vat_number>\n          <card_type>Visa</card_type>\n          <year type=\"integer\">2015</year>\n          <month type=\"integer\">11</month>\n          <first_six>411111</first_six>\n          <last_four>1111</last_four>\n        </billing_info>\n      </account>\n    </details>\n    <a name=\"refund\" href=\"http://api.test.host/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" method=\"delete\"/>\n  </transaction>\n  <!-- Continued... -->\n</transactions>","name":""}]},"settings":"","url":"/accounts/:account_code/transactions"},"body":"","category":"5595cb2ad4c23b0d00adf6ea","createdAt":"2015-06-17T23:00:38.761Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"555fbba928249c1900618a82","slug":"list-accounts-transactions","sync_unique":"","title":"List Account's Transactions","type":"get","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getList Account's Transactions


state:
String
The state of transactions to return: "successful", "failed", or "voided".
type:
String
The type of transactions to return: "authorization", "refund", or "purchase".
cursor:
String
Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
per_page:
String50
Number of records to return per page, up to a maximum of 200.

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":5,"_id":"5595cb2bd4c23b0d00adf702","api":{"auth":"required","examples":{"codes":[{"name":"","code":"try {\n  $transaction = Recurly_Transaction::get('2fded63ed07715c29c680a42c78d8ce6');\n\n  print \"Transaction: $transaction\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Transaction not found: $e\";\n}","language":"php"},{"code":"transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')","language":"ruby"},{"code":"transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')","language":"python"},{"code":"var transaction = Transactions.Get(\"a13acd8fe4294916b79aec87b7ea441f\");","language":"csharp"}]},"params":[{"_id":"55bbe4751db0f71700ab3b52","required":true,"desc":"Unique transaction id","default":"","type":"string","name":"uuid"},{"_id":"55bbe4751db0f71700ab3b51","required":false,"desc":"\"purchase\", \"authorization\" or \"refund\"","default":"","type":"string","name":"action"},{"_id":"55bbe4751db0f71700ab3b50","required":false,"desc":"Total transaction amount in cents","default":"","type":"int","name":"amount_in_cents"},{"_id":"55bbe4751db0f71700ab3b4f","required":false,"desc":"Amount of tax or VAT within the transaction, in cents","default":"","type":"int","name":"tax_in_cents"},{"_id":"55bbe4751db0f71700ab3b4e","required":false,"desc":"3-letter currency for the transaction","default":"","type":"string","name":"currency"},{"_id":"55bbe4751db0f71700ab3b4d","required":false,"desc":"\"success\", \"failed\", or \"void\"","default":"","type":"string","name":"status"},{"_id":"55bbe4751db0f71700ab3b4c","required":false,"desc":"\"credit_card\", \"paypal\", \"check\", \"wire_transfer\", \"money_order\"","default":"","type":"string","name":"payment_method"},{"_id":"55bbe4751db0f71700ab3b4b","required":false,"desc":"Transaction reference from your payment gateway","default":"","type":"string","name":"reference"},{"_id":"55bbe4751db0f71700ab3b4a","required":false,"desc":"Source of the transaction. Possible values: `transaction` for one-time transactions, `subscription` for subscriptions, `billing_info` for updating billing info.","default":"","type":"string","name":"source"},{"_id":"55bbe4751db0f71700ab3b49","required":false,"desc":"True if transaction is recurring","default":"","type":"boolean","name":"recurring"},{"_id":"55bbe4751db0f71700ab3b48","required":false,"desc":"True if test transaction","default":"","type":"boolean","name":"test"},{"_id":"55bbe4751db0f71700ab3b47","required":false,"desc":"True if the transaction may be voidable, accuracy depends on your gateway","default":"","type":"boolean","name":"voidable"},{"_id":"55bbe4751db0f71700ab3b46","required":false,"desc":"True if the transaction may be refunded","default":"","type":"string","name":"refundable"},{"_id":"55bbe4751db0f71700ab3b45","required":false,"desc":"Customer's IP address on the transaction, if applicable","default":"","type":"string","name":"ip_address"},{"_id":"55bbe4751db0f71700ab3b44","required":false,"desc":"CVV result, if applicable","default":"","type":"string","name":"cvv_result"},{"_id":"55bbe4751db0f71700ab3b43","required":false,"desc":"AVS result, if applicable","default":"","type":"string","name":"avs_result"},{"_id":"55bbe4751db0f71700ab3b42","required":false,"desc":"AVS result for the street address, line 1","default":"","type":"string","name":"avs_result_street"},{"_id":"55bbe4751db0f71700ab3b41","required":false,"desc":"AVS result for the postal code","default":"","type":"string","name":"avs_result_postal"},{"_id":"55bbe4751db0f71700ab3b40","required":false,"desc":"Date  the transaction took place","default":"","type":"string","name":"created_at"},{"_id":"55bbe4751db0f71700ab3b3f","required":false,"desc":"Nested account and billing information submitted at the time of the transaction. When writing a client library, do not map these directly to Account or Billing Info objects.","default":"","type":"string","name":"details"},{"_id":"55bbe4751db0f71700ab3b3e","required":false,"desc":"For declined transactions, the error code (if applicable).","default":"","type":"string","name":"error_code"},{"_id":"55bbe4751db0f71700ab3b3d","required":false,"desc":"For declined transactions, the error category (if applicable).","default":"","type":"string","name":"error_category"},{"_id":"55bbe4751db0f71700ab3b3c","required":false,"desc":"For declined transactions, the message displayed to the merchant (if applicable).","default":"","type":"string","name":"merchant_message"},{"_id":"55bbe4751db0f71700ab3b3b","required":false,"desc":"For declined transactions, the message displayed to the customer (if applicable).","default":"","type":"string","name":"customer_message"},{"_id":"55bbe4751db0f71700ab3b3a","required":false,"desc":"For declined transactions, this field lists the gateway error code sent to us from the gateway (if applicable).","default":"","type":"string","name":"gateway_error_code"}],"results":{"codes":[{"status":200,"language":"xml","code":"<transaction href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <subscription href=\"https://your-subdomain.recurly.com/v2/subscriptions/17caaca1716f33572edc8146e0aaefde\"/>\n  <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>\n  <action>purchase</action>\n  <amount_in_cents type=\"integer\">1000</amount_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <currency>USD</currency>\n  <status>success</status>\n  <payment_method>credit_card</payment_method>\n  <reference nil=\"nil\"></reference>\n  <source>subscription</source>\n  <recurring type=\"boolean\">true</recurring>\n  <test type=\"boolean\">true</test>\n  <voidable type=\"boolean\">true</voidable>\n  <refundable type=\"boolean\">true</refundable>\n  <ip_address>127.0.0.1</ip_address>\n  <cvv_result code=\"\" nil=\"nil\"></cvv_result>\n  <avs_result code=\"\" nil=\"nil\"></avs_result>\n  <avs_result_street nil=\"nil\"></avs_result_street>\n  <avs_result_postal nil=\"nil\"></avs_result_postal>\n  <created_at type=\"datetime\">2011-06-27T12:34:56Z</created_at>\n  <details>\n    <account>\n      <account_code>verena100</account_code>\n      <first_name>Verena</first_name>\n      <last_name>Example</last_name>\n      <company nil=\"nil\"></company>\n      <email>verena@test.com</email>\n      <billing_info type=\"credit_card\">\n        <first_name nil=\"nil\"></first_name>\n        <last_name nil=\"nil\"></last_name>\n        <address1 nil=\"nil\"></address1>\n        <address2 nil=\"nil\"></address2>\n        <city nil=\"nil\"></city>\n        <state nil=\"nil\"></state>\n        <zip nil=\"nil\"></zip>\n        <country nil=\"nil\"></country>\n        <phone nil=\"nil\"></phone>\n        <vat_number nil=\"nil\"></vat_number>\n        <card_type>Visa</card_type>\n        <year type=\"integer\">2015</year>\n        <month type=\"integer\">11</month>\n        <first_six>411111</first_six>\n        <last_four>1111</last_four>\n      </billing_info>\n    </account>\n  </details>\n  <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" method=\"delete\"/>\n</transaction>","name":""}]},"settings":"","url":"/transactions/:uuid"},"body":"","category":"5595cb2ad4c23b0d00adf6ea","createdAt":"2015-06-17T23:13:45.507Z","excerpt":"The details section contains the account and billing information at the time the transaction was submitted. It may not reflect the latest account information. A transaction_error section may be included if the transaction failed. Please see [transaction error codes](https://recurly.readme.io/v2.0/page/transaction-errors) for more details.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":2,"project":"555fbba928249c1900618a82","slug":"lookup-transaction","sync_unique":"","title":"Lookup Transaction","type":"get","updates":["55bbdca91067fc1700510eeb"],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

getLookup Transaction

The details section contains the account and billing information at the time the transaction was submitted. It may not reflect the latest account information. A transaction_error section may be included if the transaction failed. Please see [transaction error codes](https://recurly.readme.io/v2.0/page/transaction-errors) for more details.

uuid:
required
String
Unique transaction id
action:
String
"purchase", "authorization" or "refund"
amount_in_cents:
Integer
Total transaction amount in cents
tax_in_cents:
Integer
Amount of tax or VAT within the transaction, in cents
currency:
String
3-letter currency for the transaction
status:
String
"success", "failed", or "void"
payment_method:
String
"credit_card", "paypal", "check", "wire_transfer", "money_order"
reference:
String
Transaction reference from your payment gateway
source:
String
Source of the transaction. Possible values: `transaction` for one-time transactions, `subscription` for subscriptions, `billing_info` for updating billing info.
recurring:
Boolean
True if transaction is recurring
test:
Boolean
True if test transaction
voidable:
Boolean
True if the transaction may be voidable, accuracy depends on your gateway
refundable:
String
True if the transaction may be refunded
ip_address:
String
Customer's IP address on the transaction, if applicable
cvv_result:
String
CVV result, if applicable
avs_result:
String
AVS result, if applicable
avs_result_street:
String
AVS result for the street address, line 1
avs_result_postal:
String
AVS result for the postal code
created_at:
String
Date the transaction took place
details:
String
Nested account and billing information submitted at the time of the transaction. When writing a client library, do not map these directly to Account or Billing Info objects.
error_code:
String
For declined transactions, the error code (if applicable).
error_category:
String
For declined transactions, the error category (if applicable).
merchant_message:
String
For declined transactions, the message displayed to the merchant (if applicable).
customer_message:
String
For declined transactions, the message displayed to the customer (if applicable).
gateway_error_code:
String
For declined transactions, this field lists the gateway error code sent to us from the gateway (if applicable).

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":2,"_id":"5595cb2bd4c23b0d00adf703","api":{"auth":"required","examples":{"codes":[{"language":"php","code":"$transaction = new Recurly_Transaction();\n$transaction->amount_in_cents = 1000; // $10.00.\n$transaction->currency = 'USD';\n\n$account = new Recurly_Account();\n$account->account_code = '1';\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->first_name = 'Verena';\n$billing_info->last_name = 'Example';\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->verification_value = '123';\n$billing_info->month = 11;\n$billing_info->year = 2015;\n\n$account->billing_info = $billing_info;\n$transaction->account = $account;\n\n$transaction->create();","name":""},{"language":"ruby","code":"transaction = Recurly::Transaction.create(\n  :amount_in_cents => 10_00,\n  :currency        => 'USD',\n  :account         => {\n    :account_code => '1',\n    :billing_info => {\n      :first_name         => 'Verena',\n      :last_name          => 'Example',\n      :number             => '4111-1111-1111-1111',\n      :verification_value => '123',\n      :month              => 11,\n      :year               => 2015\n    }\n  }\n)"},{"language":"python","code":"transaction = Transaction(\n  amount_in_cents=1000,\n  currency='USD',\n  account=Account(\n    account_code=account_code,\n    billing_info=BillingInfo(\n      first_name='Verena',\n      last_name='Example',\n      number='4111-1111-1111-1111',\n      verification_value='123',\n      year=2015',\n      month=11\n    )\n  )\n)\ntransaction.save()"},{"language":"csharp","code":"var account = Accounts.Get(\"1\");\naccount.BillingInfo = new BillingInfo(account.AccountCode)\n{\n\tFirstName = \"Verana\",\n\tLastName = \"Example\",\n\tCreditCardNumber = \"4111-1111-1111-1111\",\n\tVerificationValue = \"123\",\n\tExpirationYear = 2015,\n\tExpirationMonth = 11\n};\nvar transaction = new Transaction(account, 100, \"USD\");\ntransaction.Create();"},{"language":"xml","code":"// Example with Stored Billing Info\n<transaction>\n  <amount_in_cents>100</amount_in_cents>\n  <currency>USD</currency>\n  <account>\n    <account_code>1</account_code>\n  </account>\n</transaction>\n\n// Example with new Billing Info\n<transaction>\n  <amount_in_cents>1000</amount_in_cents>\n  <currency>USD</currency>\n  <account>\n    <account_code>1</account_code>\n    <billing_info>\n      <first_name>Verena</first_name>\n      <last_name>Example</last_name>\n      <address1>123 Main St.</address1>\n      <city>San Francisco</city>\n      <zip>94105</zip>\n      <country>US</country>\n      <number>4111-1111-1111-1111</number>\n      <verification_value>123</verification_value>\n      <month>11</month>\n      <year>2015</year>\n    </billing_info>\n  </account>\n</transaction>"}]},"params":[{"_id":"558205eba5474a0d00d94770","required":true,"desc":"Amount of the transaction in cents. Max 10000000.","default":"","type":"int","name":"amount_in_cents"},{"_id":"558205eba5474a0d00d9476f","required":true,"desc":"3-letter currency for the transaction","default":"","type":"string","name":"currency"},{"_id":"558205eba5474a0d00d9476d","required":true,"desc":"nested attributes (see below)","default":"","type":"object","name":"account"},{"_id":"558205eba5474a0d00d9476c","required":true,"desc":"A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters.","default":"","type":"string","name":"account_code"},{"_id":"558205eba5474a0d00d9476e","required":false,"desc":"A description for the transaction. Description is added to the invoiced charge, and not the transaction object","default":"","type":"string","name":"description"},{"_id":"558205eba5474a0d00d9476b","required":false,"desc":"Username, ignore if you do not use usernames","default":"","type":"string","name":"username"},{"_id":"558205eba5474a0d00d9476a","required":false,"desc":"Email address","default":"","type":"string","name":"email"},{"_id":"558205eba5474a0d00d94769","required":false,"desc":"First name. Max of 50 characters.","default":"","type":"string","name":"first_name"},{"_id":"558205eba5474a0d00d94768","required":false,"desc":"Last name. Max of 50 characters.","default":"","type":"string","name":"last_name"},{"_id":"558205eba5474a0d00d94767","required":false,"desc":"Company name. Max of 50 characters.","default":"","type":"string","name":"company_name"},{"_id":"558205eba5474a0d00d94766","required":false,"desc":"An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.","default":"","type":"string","name":"accept_language"},{"_id":"558205eba5474a0d00d94765","required":true,"desc":"account->billing_info nested attributes (see below)","default":"","type":"object","name":"billing_info"},{"_id":"558205eba5474a0d00d94764","required":true,"desc":"First Name. Max 50 characters.","default":"","type":"string","name":"first_name"},{"_id":"558205eba5474a0d00d94763","required":true,"desc":"Last Name. Max 50 characters.","default":"","type":"string","name":"last_name"},{"_id":"558205eba5474a0d00d94762","required":false,"desc":"Company name. Max of 50 characters.","default":"","type":"string","name":"company"},{"_id":"558205eba5474a0d00d94761","required":false,"desc":"Address line 1, recommended for address validation. Max 50 characters.","default":"","type":"string","name":"address1"},{"_id":"558205eba5474a0d00d94760","required":false,"desc":"Address line 2. Max 50 characters.","default":"","type":"string","name":"address2"},{"_id":"558205eba5474a0d00d9475f","required":false,"desc":"City. Max 50 characters. Strongly Recommended","default":"","type":"string","name":"city"},{"_id":"558205eba5474a0d00d9475e","required":false,"desc":"State or Province, 2-letters preferred","default":"","type":"string","name":"state"},{"_id":"558205eba5474a0d00d9475d","required":false,"desc":"Country, 2-letter ISO code. Strongly Recommended","default":"","type":"string","name":"country"},{"_id":"558205eba5474a0d00d9475c","required":false,"desc":"Zip or postal code, recommended for address validation. Strongly Recommended","default":"","type":"string","name":"zip"},{"_id":"558205eba5474a0d00d9475b","required":false,"desc":"Phone number","default":"","type":"string","name":"phone"},{"_id":"558205eba5474a0d00d9475a","required":false,"desc":"Customer's VAT Number","default":"","type":"string","name":"vat_number"},{"_id":"558205eba5474a0d00d94759","required":false,"desc":"Customer's IP address when updating their billing information. Strongly Recommended.","default":"","type":"string","name":"ip_address"},{"_id":"558205eba5474a0d00d94758","required":true,"desc":"Credit card number, spaces and dashes are accepted.","default":"","type":"string","name":"number"},{"_id":"558205eba5474a0d00d94757","required":true,"desc":"Expiration Month","default":"","type":"string","name":"month"},{"_id":"558205eba5474a0d00d94756","required":true,"desc":"Expiration Year","default":"","type":"string","name":"year"},{"_id":"558205eba5474a0d00d94755","required":false,"desc":"Security code or CVV, 3-4 digits. Strongly Recommended.","default":"","type":"string","name":"verification_value"},{"_id":"55a92fab27a17d210052528b","required":false,"desc":"Accounting code. Max of 20 characters.","default":"","type":"string","name":"accounting_code"},{"_id":"55a92fab27a17d210052528a","required":false,"desc":"`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, defaults to `false`.","default":"false","type":"boolean","name":"tax_exempt"},{"_id":"55a92fab27a17d2100525289","required":false,"desc":"Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules","default":"","type":"string","name":"tax_code"}],"results":{"codes":[{"status":201,"language":"xml","code":"<transaction href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" type=\"credit_card\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1108\"/>\n  <uuid>a13acd8fe4294916b79aec87b7ea441f</uuid>\n  <action>purchase</action>\n  <amount_in_cents type=\"integer\">1000</amount_in_cents>\n  <tax_in_cents type=\"integer\">0</tax_in_cents>\n  <currency>USD</currency>\n  <status>success</status>\n  <payment_method>credit_card</payment_method>\n  <reference>7367829</reference>\n  <source>transaction</source>\n  <recurring type=\"boolean\">false</recurring>\n  <test type=\"boolean\">true</test>\n  <voidable type=\"boolean\">true</voidable>\n  <refundable type=\"boolean\">true</refundable>\n  <ip_address nil=\"nil\"/>\n  <cvv_result code=\"M\">Match</cvv_result>\n  <avs_result code=\"D\">Street address and postal code match.</avs_result>\n  <avs_result_street nil=\"nil\"/>\n  <avs_result_postal nil=\"nil\"/>\n  <created_at type=\"datetime\">2015-06-18T22:15:06Z</created_at>\n  <details>\n    <account>\n      <account_code>1</account_code>\n      <first_name nil=\"nil\"/>\n      <last_name nil=\"nil\"/>\n      <company nil=\"nil\"/>\n      <email nil=\"nil\"/>\n      <billing_info type=\"credit_card\">\n        <first_name>Verena</first_name>\n        <last_name>Example</last_name>\n        <address1>123 Main St.</address1>\n        <address2 nil=\"nil\"/>\n        <city>San Francisco</city>\n        <state>CA</state>\n        <zip>94105</zip>\n        <country>US</country>\n        <phone nil=\"nil\"/>\n        <vat_number nil=\"nil\"/>\n        <card_type>Visa</card_type>\n        <year type=\"integer\">2015</year>\n        <month type=\"integer\">11</month>\n        <first_six>411111</first_six>\n        <last_four>1111</last_four>\n      </billing_info>\n    </account>\n  </details>\n  <a name=\"refund\" href=\"https://your-subdomain.recurly.com/v2/transactions/a13acd8fe4294916b79aec87b7ea441f\" method=\"delete\"/>\n</transaction>","name":""}]},"settings":"","url":"/transactions"},"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using stored billing info\"\n}\n[/block]\nYou may create a transaction without specifying billing information if an account already has stored billing information.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<transaction>\\n  <amount_in_cents>100</amount_in_cents>\\n  <currency>USD</currency>\\n  <account>\\n    <account_code>1</account_code>\\n  </account>\\n</transaction>\",\n      \"language\": \"xml\"\n    },\n    {\n      \"code\": \"$transaction = new Recurly_Transaction();\\n$transaction->amount_in_cents = 100; // $1.00\\n$transaction->currency = 'USD';\\n\\n$transaction->account = new Recurly_Account();\\n$transaction->account->account_code = '1';\\n\\n$transaction->create();\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"transaction = account.transactions.create(\\n  :amount_in_cents => 1_00,\\n  :currency        => 'USD',\\n  :account         => { :account_code => '1' }\\n)\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"transaction = Transaction(\\n  amount_in_cents=100,\\n  currency='USD',\\n  account=Account(account_code='1')\\n)\\ntransaction.save()\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var transaction = new Transaction(\\\"1\\\", 100, \\\"USD\\\"); // account code, unit amount in cents, currency\\ntransaction.Create();\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using Existing Billing Info\"\n}\n[/block]\nAfter a successful transaction, the billing information will be saved with the account for future purchases. If the account already has stored billing info, the billing info from the last transaction will be saved in its place.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Accept: application/xml\\nContent-Type: application/xml; charset=utf-8\\n\\n<transaction>\\n  <amount_in_cents>1000</amount_in_cents>\\n  <currency>USD</currency>\\n  <account>\\n    <account_code>1</account_code>\\n    <billing_info>\\n      <first_name>Verena</first_name>\\n      <last_name>Example</last_name>\\n      <address1>123 Main St.</address1>\\n      <city>San Francisco</city>\\n      <zip>94105</zip>\\n      <country>US</country>\\n      <number>4111-1111-1111-1111</number>\\n      <verification_value>123</verification_value>\\n      <month>11</month>\\n      <year>2015</year>\\n    </billing_info>\\n  </account>\\n</transaction>\",\n      \"language\": \"xml\"\n    },\n    {\n      \"code\": \"$transaction = new Recurly_Transaction();\\n$transaction->amount_in_cents = 1000; // $10.00.\\n$transaction->currency = 'USD';\\n\\n$account = new Recurly_Account();\\n$account->account_code = '1';\\n\\n$billing_info = new Recurly_BillingInfo();\\n$billing_info->first_name = 'Verena';\\n$billing_info->last_name = 'Example';\\n$billing_info->number = '4111-1111-1111-1111';\\n$billing_info->verification_value = '123';\\n$billing_info->month = 11;\\n$billing_info->year = 2015;\\n\\n$account->billing_info = $billing_info;\\n$transaction->account = $account;\\n\\n$transaction->create();\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"transaction = Recurly::Transaction.create(\\n  :amount_in_cents => 10_00,\\n  :currency        => 'USD',\\n  :account         => {\\n    :account_code => '1',\\n    :billing_info => {\\n      :first_name         => 'Verena',\\n      :last_name          => 'Example',\\n      :number             => '4111-1111-1111-1111',\\n      :verification_value => '123',\\n      :month              => 11,\\n      :year               => 2015\\n    }\\n  }\\n)\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"transaction = Transaction(\\n  amount_in_cents=1000,\\n  currency='USD',\\n  account=Account(\\n    account_code=account_code,\\n    billing_info=BillingInfo(\\n      first_name='Verena',\\n      last_name='Example',\\n      number='4111-1111-1111-1111',\\n      verification_value='123',\\n      year=2015',\\n      month=11\\n    )\\n  )\\n)\\ntransaction.save()\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var account = Accounts.Get(\\\"1\\\");\\naccount.BillingInfo = new BillingInfo(account.AccountCode)\\n{\\n\\tFirstName = \\\"Verana\\\",\\n\\tLastName = \\\"Example\\\",\\n\\tCreditCardNumber = \\\"4111-1111-1111-1111\\\",\\n\\tVerificationValue = \\\"123\\\",\\n\\tExpirationYear = 2015,\\n\\tExpirationMonth = 11\\n};\\nvar transaction = new Transaction(account, 100, \\\"USD\\\");\\ntransaction.Create();\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ea","createdAt":"2015-06-17T23:42:34.999Z","excerpt":"The Recurly API provides a shortcut for creating an invoice, charge, and optionally account, and processing the payment immediately. When creating an account all of the required account attributes must be supplied. When charging an existing account only the account_code must be supplied.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"555fbba928249c1900618a82","slug":"create-transaction","sync_unique":"","title":"Create Transaction","type":"post","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

postCreate Transaction

The Recurly API provides a shortcut for creating an invoice, charge, and optionally account, and processing the payment immediately. When creating an account all of the required account attributes must be supplied. When charging an existing account only the account_code must be supplied.

amount_in_cents:
required
Integer
Amount of the transaction in cents. Max 10000000.
currency:
required
String
3-letter currency for the transaction
account:
required
Object
nested attributes (see below)
account_code:
required
String
A unique identifier used by your application to identify the account. This code may only contain the following characters: [a-z A-Z 0-9 @ - _ .]. Max of 50 characters.
description:
String
A description for the transaction. Description is added to the invoiced charge, and not the transaction object
username:
String
Username, ignore if you do not use usernames
email:
String
Email address
first_name:
String
First name. Max of 50 characters.
last_name:
String
Last name. Max of 50 characters.
company_name:
String
Company name. Max of 50 characters.
accept_language:
String
An ISO 639-1 language code from the user's browser, indicating their preferred language and locale.
billing_info:
required
Object
account->billing_info nested attributes (see below)
first_name:
required
String
First Name. Max 50 characters.
last_name:
required
String
Last Name. Max 50 characters.
company:
String
Company name. Max of 50 characters.
address1:
String
Address line 1, recommended for address validation. Max 50 characters.
address2:
String
Address line 2. Max 50 characters.
city:
String
City. Max 50 characters. Strongly Recommended
state:
String
State or Province, 2-letters preferred
country:
String
Country, 2-letter ISO code. Strongly Recommended
zip:
String
Zip or postal code, recommended for address validation. Strongly Recommended
phone:
String
Phone number
vat_number:
String
Customer's VAT Number
ip_address:
String
Customer's IP address when updating their billing information. Strongly Recommended.
number:
required
String
Credit card number, spaces and dashes are accepted.
month:
required
String
Expiration Month
year:
required
String
Expiration Year
verification_value:
String
Security code or CVV, 3-4 digits. Strongly Recommended.
accounting_code:
String
Accounting code. Max of 20 characters.
tax_exempt:
Booleanfalse
`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, defaults to `false`.
tax_code:
String
Optional field for EU VAT merchants and Avalara AvaTax Pro merchants. If you are using Recurly's EU VAT feature, you can use values of 'unknown', 'physical', or 'digital'. If you have your own AvaTax account configured, you can use Avalara tax codes to assign custom tax rules
[block:api-header] { "type": "basic", "title": "Using stored billing info" } [/block] You may create a transaction without specifying billing information if an account already has stored billing information. [block:code] { "codes": [ { "code": "<transaction>\n <amount_in_cents>100</amount_in_cents>\n <currency>USD</currency>\n <account>\n <account_code>1</account_code>\n </account>\n</transaction>", "language": "xml" }, { "code": "$transaction = new Recurly_Transaction();\n$transaction->amount_in_cents = 100; // $1.00\n$transaction->currency = 'USD';\n\n$transaction->account = new Recurly_Account();\n$transaction->account->account_code = '1';\n\n$transaction->create();", "language": "php" }, { "code": "transaction = account.transactions.create(\n :amount_in_cents => 1_00,\n :currency => 'USD',\n :account => { :account_code => '1' }\n)", "language": "ruby" }, { "code": "transaction = Transaction(\n amount_in_cents=100,\n currency='USD',\n account=Account(account_code='1')\n)\ntransaction.save()", "language": "python" }, { "code": "var transaction = new Transaction(\"1\", 100, \"USD\"); // account code, unit amount in cents, currency\ntransaction.Create();", "language": "csharp" } ] } [/block] [block:api-header] { "type": "basic", "title": "Using Existing Billing Info" } [/block] After a successful transaction, the billing information will be saved with the account for future purchases. If the account already has stored billing info, the billing info from the last transaction will be saved in its place. [block:code] { "codes": [ { "code": "Accept: application/xml\nContent-Type: application/xml; charset=utf-8\n\n<transaction>\n <amount_in_cents>1000</amount_in_cents>\n <currency>USD</currency>\n <account>\n <account_code>1</account_code>\n <billing_info>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <address1>123 Main St.</address1>\n <city>San Francisco</city>\n <zip>94105</zip>\n <country>US</country>\n <number>4111-1111-1111-1111</number>\n <verification_value>123</verification_value>\n <month>11</month>\n <year>2015</year>\n </billing_info>\n </account>\n</transaction>", "language": "xml" }, { "code": "$transaction = new Recurly_Transaction();\n$transaction->amount_in_cents = 1000; // $10.00.\n$transaction->currency = 'USD';\n\n$account = new Recurly_Account();\n$account->account_code = '1';\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->first_name = 'Verena';\n$billing_info->last_name = 'Example';\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->verification_value = '123';\n$billing_info->month = 11;\n$billing_info->year = 2015;\n\n$account->billing_info = $billing_info;\n$transaction->account = $account;\n\n$transaction->create();", "language": "php" }, { "code": "transaction = Recurly::Transaction.create(\n :amount_in_cents => 10_00,\n :currency => 'USD',\n :account => {\n :account_code => '1',\n :billing_info => {\n :first_name => 'Verena',\n :last_name => 'Example',\n :number => '4111-1111-1111-1111',\n :verification_value => '123',\n :month => 11,\n :year => 2015\n }\n }\n)", "language": "ruby" }, { "code": "transaction = Transaction(\n amount_in_cents=1000,\n currency='USD',\n account=Account(\n account_code=account_code,\n billing_info=BillingInfo(\n first_name='Verena',\n last_name='Example',\n number='4111-1111-1111-1111',\n verification_value='123',\n year=2015',\n month=11\n )\n )\n)\ntransaction.save()", "language": "python" }, { "code": "var account = Accounts.Get(\"1\");\naccount.BillingInfo = new BillingInfo(account.AccountCode)\n{\n\tFirstName = \"Verana\",\n\tLastName = \"Example\",\n\tCreditCardNumber = \"4111-1111-1111-1111\",\n\tVerificationValue = \"123\",\n\tExpirationYear = 2015,\n\tExpirationMonth = 11\n};\nvar transaction = new Transaction(account, 100, \"USD\");\ntransaction.Create();", "language": "csharp" } ] } [/block]

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



[block:api-header] { "type": "basic", "title": "Using stored billing info" } [/block] You may create a transaction without specifying billing information if an account already has stored billing information. [block:code] { "codes": [ { "code": "<transaction>\n <amount_in_cents>100</amount_in_cents>\n <currency>USD</currency>\n <account>\n <account_code>1</account_code>\n </account>\n</transaction>", "language": "xml" }, { "code": "$transaction = new Recurly_Transaction();\n$transaction->amount_in_cents = 100; // $1.00\n$transaction->currency = 'USD';\n\n$transaction->account = new Recurly_Account();\n$transaction->account->account_code = '1';\n\n$transaction->create();", "language": "php" }, { "code": "transaction = account.transactions.create(\n :amount_in_cents => 1_00,\n :currency => 'USD',\n :account => { :account_code => '1' }\n)", "language": "ruby" }, { "code": "transaction = Transaction(\n amount_in_cents=100,\n currency='USD',\n account=Account(account_code='1')\n)\ntransaction.save()", "language": "python" }, { "code": "var transaction = new Transaction(\"1\", 100, \"USD\"); // account code, unit amount in cents, currency\ntransaction.Create();", "language": "csharp" } ] } [/block] [block:api-header] { "type": "basic", "title": "Using Existing Billing Info" } [/block] After a successful transaction, the billing information will be saved with the account for future purchases. If the account already has stored billing info, the billing info from the last transaction will be saved in its place. [block:code] { "codes": [ { "code": "Accept: application/xml\nContent-Type: application/xml; charset=utf-8\n\n<transaction>\n <amount_in_cents>1000</amount_in_cents>\n <currency>USD</currency>\n <account>\n <account_code>1</account_code>\n <billing_info>\n <first_name>Verena</first_name>\n <last_name>Example</last_name>\n <address1>123 Main St.</address1>\n <city>San Francisco</city>\n <zip>94105</zip>\n <country>US</country>\n <number>4111-1111-1111-1111</number>\n <verification_value>123</verification_value>\n <month>11</month>\n <year>2015</year>\n </billing_info>\n </account>\n</transaction>", "language": "xml" }, { "code": "$transaction = new Recurly_Transaction();\n$transaction->amount_in_cents = 1000; // $10.00.\n$transaction->currency = 'USD';\n\n$account = new Recurly_Account();\n$account->account_code = '1';\n\n$billing_info = new Recurly_BillingInfo();\n$billing_info->first_name = 'Verena';\n$billing_info->last_name = 'Example';\n$billing_info->number = '4111-1111-1111-1111';\n$billing_info->verification_value = '123';\n$billing_info->month = 11;\n$billing_info->year = 2015;\n\n$account->billing_info = $billing_info;\n$transaction->account = $account;\n\n$transaction->create();", "language": "php" }, { "code": "transaction = Recurly::Transaction.create(\n :amount_in_cents => 10_00,\n :currency => 'USD',\n :account => {\n :account_code => '1',\n :billing_info => {\n :first_name => 'Verena',\n :last_name => 'Example',\n :number => '4111-1111-1111-1111',\n :verification_value => '123',\n :month => 11,\n :year => 2015\n }\n }\n)", "language": "ruby" }, { "code": "transaction = Transaction(\n amount_in_cents=1000,\n currency='USD',\n account=Account(\n account_code=account_code,\n billing_info=BillingInfo(\n first_name='Verena',\n last_name='Example',\n number='4111-1111-1111-1111',\n verification_value='123',\n year=2015',\n month=11\n )\n )\n)\ntransaction.save()", "language": "python" }, { "code": "var account = Accounts.Get(\"1\");\naccount.BillingInfo = new BillingInfo(account.AccountCode)\n{\n\tFirstName = \"Verana\",\n\tLastName = \"Example\",\n\tCreditCardNumber = \"4111-1111-1111-1111\",\n\tVerificationValue = \"123\",\n\tExpirationYear = 2015,\n\tExpirationMonth = 11\n};\nvar transaction = new Transaction(account, 100, \"USD\");\ntransaction.Create();", "language": "csharp" } ] } [/block]
{"__v":0,"_id":"5595cb2bd4c23b0d00adf704","api":{"auth":"required","params":[{"_id":"55820a86a5474a0d00d94783","required":false,"desc":"Amount to refund in cents. Defaults to full amount.","default":"","type":"int","name":"amount_in_cents"}],"results":{"codes":[{"status":204,"language":"json","code":"Status: 204 No Content","name":""}]},"settings":"","url":""},"body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"We are moving to refunds through the Invoice object. Transaction refunds will no longer work if you have switched to Invoice Refunds in your Site Settings. If you created your site after November 11, 2014, you are automatically on Invoice refunds. Please see our API documentation on Invoices.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Partial Refunds\"\n}\n[/block]\nIf the transaction has not settled and you attempt a partial refund, the request will fail. Please wait until the transaction has settled (typically 24 hours) before performing a partial refund. This advice varies depending on when your payment gateway settles the transaction.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\\n$transaction->refund(1000); // Refund $10.00.\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\\ntransaction.refund(10_00)\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\\ntransaction.refund(amount_in_cents=1000)\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var transaction = Transactions.Get(\\\"a13acd8fe4294916b79aec87b7ea441f\\\");\\ntransaction.Refund(1000); // (in cents) Refund $10\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Full Refunds\"\n}\n[/block]\nIf the transaction has not settled and you perform a full refund, the transaction will be voided instead. Voided transactions typically do not show up on the customer's card statement. If the transaction has settled, a refund will be performed.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\\n$transaction->refund();\",\n      \"language\": \"php\"\n    },\n    {\n      \"code\": \"transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\\ntransaction.refund()\",\n      \"language\": \"ruby\"\n    },\n    {\n      \"code\": \"transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\\ntransaction.refund()\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"var transaction = Transactions.Get(\\\"a13acd8fe4294916b79aec87b7ea441f\\\");\\ntransaction.Refund();\",\n      \"language\": \"csharp\"\n    }\n  ]\n}\n[/block]","category":"5595cb2ad4c23b0d00adf6ea","createdAt":"2015-06-18T00:02:14.870Z","excerpt":"A transaction can refunded if it has settled successfully. It can be refunded for any amount equal to or less than the original amount. Please note, some payment gateways do not allow the same credit card to be partially refunded on the same day as the original purchase. Using the transaction refund will not generate a refund invoice. If you need a refund invoice, you should use the invoice line item or invoice open amount refund.","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"555fbba928249c1900618a82","slug":"refund-transaction","sync_unique":"","title":"Refund Transaction (deprecated)","type":"delete","updates":[],"user":"556790090145bc23008e3bf8","version":"5595cb29d4c23b0d00adf6e3"}

deleteRefund Transaction (deprecated)

A transaction can refunded if it has settled successfully. It can be refunded for any amount equal to or less than the original amount. Please note, some payment gateways do not allow the same credit card to be partially refunded on the same day as the original purchase. Using the transaction refund will not generate a refund invoice. If you need a refund invoice, you should use the invoice line item or invoice open amount refund.

[block:callout] { "type": "danger", "body": "We are moving to refunds through the Invoice object. Transaction refunds will no longer work if you have switched to Invoice Refunds in your Site Settings. If you created your site after November 11, 2014, you are automatically on Invoice refunds. Please see our API documentation on Invoices." } [/block] [block:api-header] { "type": "basic", "title": "Partial Refunds" } [/block] If the transaction has not settled and you attempt a partial refund, the request will fail. Please wait until the transaction has settled (typically 24 hours) before performing a partial refund. This advice varies depending on when your payment gateway settles the transaction. [block:code] { "codes": [ { "code": "$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\n$transaction->refund(1000); // Refund $10.00.", "language": "php" }, { "code": "transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund(10_00)", "language": "ruby" }, { "code": "transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund(amount_in_cents=1000)", "language": "python" }, { "code": "var transaction = Transactions.Get(\"a13acd8fe4294916b79aec87b7ea441f\");\ntransaction.Refund(1000); // (in cents) Refund $10", "language": "csharp" } ] } [/block] [block:api-header] { "type": "basic", "title": "Full Refunds" } [/block] If the transaction has not settled and you perform a full refund, the transaction will be voided instead. Voided transactions typically do not show up on the customer's card statement. If the transaction has settled, a refund will be performed. [block:code] { "codes": [ { "code": "$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\n$transaction->refund();", "language": "php" }, { "code": "transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund()", "language": "ruby" }, { "code": "transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund()", "language": "python" }, { "code": "var transaction = Transactions.Get(\"a13acd8fe4294916b79aec87b7ea441f\");\ntransaction.Refund();", "language": "csharp" } ] } [/block]
[block:callout] { "type": "danger", "body": "We are moving to refunds through the Invoice object. Transaction refunds will no longer work if you have switched to Invoice Refunds in your Site Settings. If you created your site after November 11, 2014, you are automatically on Invoice refunds. Please see our API documentation on Invoices." } [/block] [block:api-header] { "type": "basic", "title": "Partial Refunds" } [/block] If the transaction has not settled and you attempt a partial refund, the request will fail. Please wait until the transaction has settled (typically 24 hours) before performing a partial refund. This advice varies depending on when your payment gateway settles the transaction. [block:code] { "codes": [ { "code": "$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\n$transaction->refund(1000); // Refund $10.00.", "language": "php" }, { "code": "transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund(10_00)", "language": "ruby" }, { "code": "transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund(amount_in_cents=1000)", "language": "python" }, { "code": "var transaction = Transactions.Get(\"a13acd8fe4294916b79aec87b7ea441f\");\ntransaction.Refund(1000); // (in cents) Refund $10", "language": "csharp" } ] } [/block] [block:api-header] { "type": "basic", "title": "Full Refunds" } [/block] If the transaction has not settled and you perform a full refund, the transaction will be voided instead. Voided transactions typically do not show up on the customer's card statement. If the transaction has settled, a refund will be performed. [block:code] { "codes": [ { "code": "$transaction = Recurly_Transaction::get('a13acd8fe4294916b79aec87b7ea441f');\n$transaction->refund();", "language": "php" }, { "code": "transaction = Recurly::Transaction.find('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund()", "language": "ruby" }, { "code": "transaction = Transaction.get('a13acd8fe4294916b79aec87b7ea441f')\ntransaction.refund()", "language": "python" }, { "code": "var transaction = Transactions.Get(\"a13acd8fe4294916b79aec87b7ea441f\");\ntransaction.Refund();", "language": "csharp" } ] } [/block]