Recurly Adjustments API

openapi: 3.2.0
info:
  title: Recurly Adjustments API
  version: '1.0'
  description: 'Operations tagged adjustments across 2 of this provider''s published API definitions: recurly-v2-api.yaml, recurly-v2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{subdomain}.recurly.com/v2
  variables:
    subdomain:
      description: Subdomain of your Recurly site.
      default: my-super-successful-company
security:
- api_key: []
tags:
- name: Adjustments
  x-displayName: Adjustments
paths:
  /accounts/{account_code}/adjustments:
    get:
      summary: List an Account's Adjustments
      description: Lists all charges and credits issued for a given account.
      tags:
      - Adjustments
      operationId: listAnAccountsAdjustments
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      - in: query
        name: type
        schema:
          type: string
          default: all
        required: false
        description: 'The type of adjustment to return: "charge" or "credit"'
      - in: query
        name: state
        schema:
          type: string
          default: all
        required: false
        description: 'The state of the adjustments to return: "pending" or "invoiced".'
      - in: query
        name: cursor
        schema:
          type: string
          default: ''
        required: false
        description: Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
      - in: query
        name: per_page
        schema:
          type: integer
          default: '50'
        required: false
        description: Number of records to return per page, up to a maximum of 200.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nX-Records: 123\nLink: <https://your-subdomain.recurly.com/v2/accounts/100/adjustments?cursor=1304958672>; rel=\"next\"\nETag: \"0d34d4e5faed7fb1b577bafbb5bb71f9\"\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<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/b6f5783\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1001\"/>\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\">2015-02-25T03:30:00Z</start_date>\n    <end_date nil=\"nil\"/>\n    <created_at type=\"datetime\">2015-02-25T03:30:00Z</created_at>\n  </adjustment>\n  <!-- Continued... -->\n</adjustments>"
      x-codeSamples:
      - lang: PHP
        source: "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}"
      - lang: Ruby
        source: "account = Recurly::Account.find('1')\naccount.adjustments.find_each do |adjustment|\n  puts \"Adjustment: #{adjustment.inspect}\"\nend"
      - lang: Python
        source: "# client version 2.1.6+\naccount = Account.get('1')\nfor adjustment in account.adjustments():\n    print 'Adjustment: %s' % adjustment\n\n# 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 = ()"
      - lang: Dotnet
        source: "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}"
    post:
      summary: Create a Charge or Credit
      description: 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.
      tags:
      - Adjustments
      operationId: createAChargeOrCredit
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Your unique account identifier.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                currency:
                  type: string
                  default: ''
                  description: Currency, 3-letter ISO code
                unit_amount_in_cents:
                  type: string
                  default: ''
                  description: Positive amount for a charge, negative amount for a credit. Max 10000000.
                description:
                  type: string
                  default: ''
                  description: Description of the adjustment for the invoice.
                quantity:
                  type: string
                  default: '1'
                  description: Quantity
                accounting_code:
                  type: string
                  default: ''
                  description: Accounting code. Max of 20 characters.
                tax_exempt:
                  type: string
                  default: ''
                  description: '`true` exempts tax on the charge, `false` applies tax on the charge. If not defined, then defaults to the Plan and Site settings.'
                tax_code:
                  type: string
                  maxLength: 50
                  title: Tax code
                  description: Optional field used by Avalara, Vertex, and Recurly's In-the-Box tax solution to determine taxation rules. You can pass in specific tax codes using any of these tax integrations. For Recurly's In-the-Box tax offering you can also choose to instead use simple values of `unknown`, `physical`, or `digital` tax codes.
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "Status: 201 Created\nContent-Type: application/xml; charset=utf-8\nLocation: https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\"/>\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>"
      x-codeSamples:
      - lang: PHP
        source: "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}"
      - lang: Ruby
        source: "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)"
      - lang: Python
        source: "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)"
      - lang: Dotnet
        source: "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();"
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
  /adjustments/{uuid}:
    get:
      summary: Get an Adjustment
      description: Returns information about a single adjustment.
      tags:
      - Adjustments
      operationId: getAnAdjustment
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          default: ''
        required: true
        description: The unique identifier for the adjustment
      - in: query
        name: type
        schema:
          type: string
          default: credits and charges
        required: false
        description: 'The type of adjustment to return: "charge" or "credit"'
      - in: query
        name: state
        schema:
          type: string
          default: active
        required: false
        description: 'The state of the adjustments to return: "pending" or "invoiced".'
      - in: query
        name: cursor
        schema:
          type: string
          default: ''
        required: false
        description: Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "Status: 200 OK\nContent-Type: application/xml; charset=utf-8\nX-Records: 123\nLink: <https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60?cursor=1304958672>; rel=\"next\"\nETag: \"0d34d4e5faed7fb1b577bafbb5bb71f9\"\n\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n  <adjustment href=\"https://your-subdomain.recurly.com/v2/adjustments/626db120a84102b1809909071c701c60\" type=\"charge\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/b6f5783\"/>\n    <invoice href=\"https://your-subdomain.recurly.com/v2/invoices/1001\"/>\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>"
      x-codeSamples:
      - lang: PHP
        source: "try {\n  $adjustment = Recurly_Adjustment::get('626db120a84102b1809909071c701c60');\n\n  print \"Adjustment: $adjustment\";\n} catch (Recurly_NotFoundError $e) {\n  print \"Invalid adjustment uuid: $e\";\n}"
      - lang: Ruby
        source: "account = Recurly::Account.find('1')\naccount.adjustments.find_each do |adjustment|\n  puts \"Adjustment: #{adjustment.inspect}\"\nend"
      - lang: Python
        source: "# client version 2.1.6+\naccount = Account.get('1')\nfor adjustment in account.adjustments():\n    print 'Adjustment: %s' % adjustment\n\n# 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 = ()"
      - lang: Dotnet
        source: 'var adjustment = Adjustments.Get("123456789");

          Console.WriteLine("Adjustment: " + adjustment);'
    delete:
      summary: Delete an Adjustment
      description: 'Delete a non-invoiced adjustment from an account.


        ###### Please note


        An adjustment may only be deleted if it has not been invoiced.'
      tags:
      - Adjustments
      operationId: deleteAnAdjustment
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          default: ''
        required: true
        description: The unique identifier for the adjustment
      responses:
        '200':
          description: ''
          content:
            application/text:
              example: ''
      x-codeSamples:
      - lang: PHP
        source: "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}"
      - lang: Ruby
        source: 'adjustment = Recurly::Adjustment.find(''945a4cb9afd64300b97b138407a51aef'')

          adjustment.destroy'
      - lang: Python
        source: 'adjustment = Adjustment.get(''945a4cb9afd64300b97b138407a51aef'')

          adjustment.delete()'
      - lang: text
        source: 'var adjustment = Adjustments.Get("945a4cb9afd64300b97b138407a51aef");

          adjustment.Delete();'
    servers:
    - url: https://{subdomain}.recurly.com/v2
      variables:
        subdomain:
          description: Subdomain of your Recurly site.
          default: my-super-successful-company
components:
  securitySchemes:
    api_key:
      type: http
      description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.
      scheme: basic
x-refined-from:
- recurly-v2-api.yaml
- recurly-v2-openapi.yml
x-readme:
  explorer-enabled: false