Invoices

Update Invoice

Changed on

Update Invoice

patch/accounting/invoices/{id}

Request

  • Base URL: https://unify.apideck.com
  • URL: https://unify.apideck.com/accounting/invoices/{id}
  • Auth: API key in header Authorization

Path parameters

idstring required

ID of the record you are acting upon.

Query parameters

rawboolean

Include raw response. Mostly used for debugging purposes

Headers

x-apideck-consumer-idstring required

ID of the consumer which you want to get or push data from

x-apideck-app-idstring required

The ID of your Unify application

x-apideck-service-idstring

Provide the service id you want to call (e.g., pipedrive). Only needed when a consumer has activated multiple integrations for a Unified API.

idempotency-keystring

A unique key you generate for one create or update, to make retrying it safe. If the request times out or fails with an uncertain outcome, resend it with the same key and the same body: the record is created, or the update applied, at most once. Keys are 1-255 printable ASCII characters (a UUID is recommended) and are accepted bare or as a quoted string. A key is remembered for 24 hours from its first use, or for the connector's own deduplication window where that is shorter (Xero: 6 minutes; Sage Intacct REST: 1 hour); after that, the same key is treated as a new request, so retry within the window. Some connectors also replay an error to retries with the same key: if retries keep returning the same error, check whether the record exists before sending it again with a new key. Reusing a key with a different body returns 422, and retrying while the first attempt is still running returns 409. A key is bound to its first request even if that request was rejected, so after fixing a rejected body, send it with a new key. Connectors that cannot honour the key on this operation reject the request with 400 instead of writing unprotected.

Request body

idstring

A unique identifier for an object.

downstream_idstring nullable

The third-party API ID of original entity

display_idstring nullable

Id to be displayed.

type'standard' | 'credit' | 'service' | 'product' | 'supplier' | 'other' nullable

Invoice type

numberstring nullable

Invoice number.

company_idstring nullable

The company ID the transaction belongs to

location_idstring nullable

The ID of the location

department_idstring nullable

The ID of the department

invoice_datestring date nullable

Date invoice was issued - YYYY-MM-DD.

due_datestring date nullable

The invoice due date is the date on which a payment or invoice is scheduled to be received by the seller - YYYY-MM-DD.

termsstring nullable

Terms of payment.

terms_idstring nullable

The ID of the payment terms

po_numberstring nullable

A PO Number uniquely identifies a purchase order and is generally defined by the buyer. The buyer will match the PO number in the invoice to the Purchase Order.

referencestring nullable

Optional reference identifier for the transaction.

status'draft' | 'submitted' | 'authorised' | 'partially_paid' | 'paid' | 'unpaid' | 'void' | 'credit' | 'deleted' | 'posted' nullable

Invoice status

invoice_sentboolean

Invoice sent to contact/customer.

currency'UNKNOWN_CURRENCY' | 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYR' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LTL' | 'LVL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRO' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STD' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRC' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'USS' | 'UYI' | 'UYU' | 'UZS' | 'VEF' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XTS' | 'XXX' | 'YER' | 'ZAR' | 'ZMK' | 'ZMW' | 'BTC' | 'ETH' nullable

Indicates the associated currency for an amount of money. Values correspond to ISO 4217.

currency_ratenumber nullable

Currency Exchange Rate at the time entity was recorded/generated.

tax_inclusiveboolean nullable

Amounts are including tax

sub_totalnumber nullable

Sub-total amount, normally before tax.

total_taxnumber nullable

Total tax amount applied to this invoice.

tax_codestring nullable

Applicable tax id/code override if tax is not supplied on a line item basis.

discount_percentagenumber nullable

Discount percentage applied to this invoice.

discount_amountnumber nullable

Discount amount applied to this invoice.

totalnumber nullable

Total amount of invoice, including tax.

balancenumber nullable

Balance of invoice due.

depositnumber nullable

Amount of deposit made to this invoice.

customer_memostring nullable

Customer memo

template_idstring nullable

Optional invoice template

source_document_urlstring nullable

URL link to a source document - shown as 'Go to [appName]' in the downstream app. Currently only supported for Xero.

payment_methodstring nullable

Payment method used for the transaction, such as cash, credit card, bank transfer, or check

channelstring nullable

The channel through which the transaction is processed.

languagestring nullable

language code according to ISO 639-1. For the United States - EN

accounting_by_rowboolean nullable

Indicates if accounting by row is used (true) or not (false). Accounting by row means that a separate ledger transaction is created for each row.

custom_mappingsCustomMappings nullable

When custom mappings are configured on the resource, the result is included here.

row_versionstring nullable

A binary value used to detect updates to a object and prevent data conflicts. It is incremented each time an update is made to the object.

updated_bystring nullable

The user who last updated the object.

created_bystring nullable

The user who created the object.

updated_atstring date-time nullable

The date and time when the object was last updated.

created_atstring date-time nullable

The date and time when the object was created.

Example request

{
  "id": "12345",
  "downstream_id": "12345",
  "display_id": "123456",
  "type": "service",
  "number": "OIT00546",
  "customer": {
    "id": "12345",
    "display_id": "CUST00101",
    "display_name": "Windsurf Shop",
    "name": "Windsurf Shop",
    "company_name": "The boring company",
    "email": "boring@boring.com"
  },
  "company_id": "12345",
  "subsidiary": {
    "id": "12345",
    "display_id": "123456",
    "name": "Acme Inc."
  },
  "location_id": "12345",
  "department_id": "12345",
  "invoice_date": "2020-09-30",
  "due_date": "2020-09-30",
  "terms": "Net 30 days",
  "terms_id": "12345",
  "po_number": "90000117",
  "reference": "INV-2024-001",
  "status": "draft",
  "invoice_sent": true,
  "currency": "USD",
  "currency_rate": 0.69,
  "tax_inclusive": true,
  "sub_total": 27500,
  "total_tax": 2500,
  "tax_code": "1234",
  "discount_percentage": 5.5,
  "discount_amount": 25,
  "total": 27500,
  "balance": 27500,
  "customer_memo": "Thank you for your business and have a great day!",
  "tracking_category": {
    "id": "123456",
    "name": "New York"
  },
  "tracking_categories": [
    {
      "id": "123456",
      "code": "100",
      "name": "New York",
      "parent_id": "123456",
      "parent_name": "New York"
    }
  ],
  "line_items": [
    {
      "id": "12345",
      "row_id": "12345",
      "code": "120-C",
      "line_number": 1,
      "description": "Model Y is a fully electric, mid-size SUV, with seating for up to seven, dual motor AWD and unparalleled protection.",
      "type": "sales_item",
      "tax_amount": 27500,
      "total_amount": 27500,
      "quantity": 1,
      "unit_price": 27500.5,
      "unit_of_measure": "pc.",
      "discount_percentage": 0.01,
      "discount_amount": 19.99,
      "service_date": "2024-01-15",
      "category_id": "12345",
      "location_id": "12345",
      "department_id": "12345",
      "subsidiary_id": "12345",
      "shipping_id": "12345",
      "memo": "Some memo",
      "prepaid": true,
      "item": {
        "id": "12344",
        "code": "120-C",
        "name": "Model Y"
      },
      "taxable": true,
      "tax_applicable_on": "Domestic_Purchase_of_Goods_and_Services",
      "tax_recoverability": "Fully_Recoverable",
      "tax_method": "Due_to_Supplier",
      "worktags": [
        {
          "id": "123456",
          "value": "New York"
        }
      ],
      "tax_rate": {
        "id": "123456",
        "code": "N-T",
        "name": "GST on Purchases",
        "rate": 10
      },
      "tracking_categories": [
        {
          "id": "123456",
          "code": "100",
          "name": "New York",
          "parent_id": "123456",
          "parent_name": "New York"
        }
      ],
      "ledger_account": {
        "id": "123456",
        "name": "Bank account",
        "nominal_code": "N091",
        "code": "453",
        "parent_id": "123456",
        "display_id": "123456"
      },
      "custom_fields": [
        {
          "id": "2389328923893298",
          "name": "employee_level",
          "ref_name": "Marketing",
          "description": "Employee Level",
          "value": "Uses Salesforce and Marketo"
        }
      ],
      "row_version": "1-12345",
      "updated_by": "12345",
      "created_by": "12345",
      "created_at": "2020-09-30T07:43:32.000Z",
      "updated_at": "2020-09-30T07:43:32.000Z"
    }
  ],
  "billing_address": {
    "id": "123",
    "type": "primary",
    "string": "25 Spring Street, Blackburn, VIC 3130",
    "name": "HQ US",
    "line1": "Main street",
    "line2": "apt #",
    "line3": "Suite #",
    "line4": "delivery instructions",
    "line5": "Attention: Finance Dept",
    "street_number": "25",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94104",
    "country": "US",
    "latitude": "40.759211",
    "longitude": "-73.984638",
    "county": "Santa Clara",
    "contact_name": "Elon Musk",
    "salutation": "Mr",
    "phone_number": "111-111-1111",
    "fax": "122-111-1111",
    "email": "elon@musk.com",
    "website": "https://elonmusk.com",
    "notes": "Address notes or delivery instructions.",
    "row_version": "1-12345"
  },
  "shipping_address": {
    "id": "123",
    "type": "primary",
    "string": "25 Spring Street, Blackburn, VIC 3130",
    "name": "HQ US",
    "line1": "Main street",
    "line2": "apt #",
    "line3": "Suite #",
    "line4": "delivery instructions",
    "line5": "Attention: Finance Dept",
    "street_number": "25",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94104",
    "country": "US",
    "latitude": "40.759211",
    "longitude": "-73.984638",
    "county": "Santa Clara",
    "contact_name": "Elon Musk",
    "salutation": "Mr",
    "phone_number": "111-111-1111",
    "fax": "122-111-1111",
    "email": "elon@musk.com",
    "website": "https://elonmusk.com",
    "notes": "Address notes or delivery instructions.",
    "row_version": "1-12345"
  },
  "template_id": "123456",
  "source_document_url": "https://www.invoicesolution.com/invoice/123456",
  "payment_allocations": [
    {
      "id": "123456",
      "allocated_amount": 1000,
      "date": "2020-09-30T07:43:32.000Z"
    }
  ],
  "payment_method": "cash",
  "channel": "email",
  "language": "EN",
  "bank_account": {
    "bank_name": "Chase Bank",
    "account_number": "123465",
    "account_name": "Main Operating Account",
    "account_type": "credit_card",
    "iban": "GB33BUKB20201555555555",
    "bic": "CHASUS33",
    "routing_number": "021000021",
    "bsb_number": "062-001",
    "branch_identifier": "001",
    "bank_code": "BNH",
    "currency": "USD",
    "country": "US"
  },
  "ledger_account": {
    "id": "123456",
    "name": "Bank account",
    "nominal_code": "N091",
    "code": "453",
    "parent_id": "123456",
    "display_id": "123456"
  },
  "custom_fields": [
    {
      "id": "2389328923893298",
      "name": "employee_level",
      "ref_name": "Marketing",
      "description": "Employee Level",
      "value": "Uses Salesforce and Marketo"
    }
  ],
  "row_version": "1-12345",
  "updated_by": "12345",
  "created_by": "12345",
  "updated_at": "2020-09-30T07:43:32.000Z",
  "created_at": "2020-09-30T07:43:32.000Z",
  "pass_through": [
    {
      "extend_paths": [
        {
          "path": "$.nested.property",
          "value": {
            "TaxClassificationRef": {
              "value": "EUC-99990201-V1-00020000"
            }
          }
        }
      ]
    }
  ]
}

Response

Invoice updated

status_codeinteger required

HTTP Response Status Code

statusstring required

HTTP Response Status

servicestring required

Apideck ID of service provider

resourcestring required

Unified API resource name

operationstring required

Operation performed

_rawRaw nullable

Raw response from the integration when raw=true query param is provided

Example response

{
  "status_code": 200,
  "status": "OK",
  "service": "xero",
  "resource": "invoices",
  "operation": "update",
  "data": {
    "id": "12345",
    "downstream_id": "12345"
  }
}

Changes

  • 68de2abf4e40Revision changes
    • info

      added the new optional header request parameter idempotency-key

  • 17a0dec24672Revision changes
    • info

      added the new optional request property //

    • info

      added the new optional request property ////