curl ruby

Introduction

# Bundler: Add to your Gemfile
gem "octobat"
API Endpoint
https://apiv2.octobat.com

The Octobat API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP verbs, which can be understood by off-the-shelf HTTP clients.

JSON will be returned in all responses from the API, including errors.

To make the Octobat API as secure as possible. Authentication is performed through HTTP Basic Auth. Credentials can be found on your Octobat developers menu, in the “API Keys” section.

Authentication

# Example request
$ curl https://apiv2.octobat.com/customers \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# curl uses the -u flag to pass basic auth credentials
# (adding a colon after your secret API key will prevent it
# from asking you for a password).
# Example request
require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

# Authentication is transparently handled for you
# in subsequent method calls.

Authentication to the API occurs via HTTP Basic Auth. Provide your API secret key as the basic auth username. You do not need to provide a password. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests. You can manage your API keys from your account. Your API keys carry many privileges, so be sure to keep them secret!

Errors

HTTP status codes summary

200 OK - Everything worked as expected.

201 Created - Resource has been successfully created

202 Accepted - Request has been accepted, but requires asynchronous work to be fully performed

400 Bad Request - Request failed due to a combination of errors

401 Unauthorized - No valid API credentials provided.

402 Payment Required - Your request was in livemode while your account is not activated for live requests yet.

403 Forbidden - You are not authorized to access the requested item.

404 Not Found - The requested item doesn't exist.

406 Unacceptable - Your request format was not supported. Use JSON.

409 Conflict - The data you submitted is in conflict with existing data.

422 Unprocessable Entity - Often missing a required parameter.

429 Too Many Requests - You sent us too many API requests in a row. Please retry later.

500, 502, 503, 504 Server errors - something went wrong on Octobat's end.

Octobat uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Octobat’s servers.

Pagination

# Example request
$ curl https://apiv2.octobat.com/customers?limit=3 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_more": true,
  "has_before": false,
  "total_count": 240,
  "data": [
    {
      "id": "oc_cu_1421878635hksc26e4de79",
      "object" : "customer",
      "name": "Octobat Inc.",
      "email": "admin@octobat.com",
      "phone_number": "+33 9 52 54 03 70",
      "billing_address_line1": null,
      "billing_address_line2": null,
      "billing_address_city": "Paris",
      "billing_address_zip": "75004",
      "billing_address_state": null,
      "billing_address_country": "France",
      "business_type": "B2C",
      "tax_number": null,
      "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
      "created_at": "2015-07-12T11:22:29Z",
      "updated_at": "2015-07-12T11:22:29Z"
    },
    {...},
    {...}
  ]
}
# Example request
require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"
Octobat::Customer.all(limit: 3)

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_more": true,
  "has_before": false,
  "total_count": 240,
  "data": [
    #<Octobat::Customer id=oc_cu_1421878635hksc26e4de79 0x00000a> JSON: {
     "id": "oc_cu_1421878635hksc26e4de79",
     "object": "customer",
     "name": "Octobat Inc.",
     "email": "admin@octobat.com",
     "phone_number": "+33 9 52 54 03 70",
     "billing_address_line1": null,
     "billing_address_line2": null,
     "billing_address_city": "Paris",
     "billing_address_zip": "75004",
     "billing_address_state": null,
     "billing_address_country": "France",
     "business_type": "B2C",
     "tax_number": null,
     "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
     "created_at": "2015-07-12T11:22:29Z",
     "updated_at": "2015-07-12T11:22:29Z"
    },
    #<Octobat::Customer[...] ...>,
    #<Octobat::Customer[...] ...>
  ]
}

All top-level Octobat API resources have support for bulk fetches “list” API methods. For instance, you can list customers, list invoices. Like Stripe, Octobat uses cursor-based pagination using the parameter starting_after. Pass starting_after parameter at the previous page last object id value to determine where to start in the list.

Attributes

Attribute Type
limit integer optional A limit on the number of objects to be returned. Must be included between 1 and 100
starting_after string optional A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before string optional A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

List response format

Attribute Type
object string, value is “list”
data array An array containing the actual response elements, paginated by any request parameters.
has_more boolean Whether or not there are more elements available after this page. If false, this page is the end of the list.
has_before boolean Whether or not there are more elements available before this page. If false, this page is the beginning of the list.
total_count boolean The total count of all recipients that match your filters, as if there was no pagination.

Source objects

Potentially Synchronized objects —including Customer, Invoice, Credit Note, Item and Transaction— have a sources parameter.

Sources references the external data this Octobat object has been created from. As an Octobat object may have been populated from several external objects, sources is always represented as an array of JSON-encoded hashes - each nested hash being a single reference -.

As an example, a customer created in Octobat from a Stripe customer includes a reference to this last one in the following form:

{'gateway': 'stripe', 'source_type': 'customer', 'identifier': 'cus_xxxxxxxx'},

so the full sources attribute value would be:

[{'gateway': 'stripe', 'source_type': 'customer', 'identifier': 'cus_xxxxxxxx'}].

Nested JSON-encoded hashes have always the same structure with the following keys:

Inner sources attributes

Attribute Type
gateway string The integration this object came from. Examples: stripe, gocardless
source_type string The platform object type. For instance, a Stripe payment is called: charge
identifier string The platform object identifier, that you can request on.

Sources are always serialized and sent back upon API requests and webhooks. A common useful case is to link the payment platform charge or subscription object to the corresponding invoice or items created in Octobat.

Expandable objects

# Example request
$ curl https://apiv2.octobat.com/customers?expand[]=invoices \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:
# Example request
require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"
Octobat::Customer.all(expand: ['invoices'])

Many objects can be nested into their parent object in their response properties. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. This parameter is available on all API requests, and applies to the response of that request only. For example, requesting invoices on a customer will add the customer’s invoices list as a property into a full customer object, and will then expand the invoices properties on that customer into a full list object.

Idempotent requests

# Example request
$ curl -X POST https://apiv2.octobat.com/customers \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:
   -H "Idempotency-Key: 6OiRDy97Nlrt4ESP" \
   -d email=contact@octobat.com \
   -d billing_address_country=FR \
   -d name=Octobat SAS
# Example request
require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Customer.create({
  email: "contact@octobat.com",
  billing_address_country: "FR",
  name: "Octobat SAS"
}, {
  idempotency_key: "6OiRDy97Nlrt4ESP"
})

The Octobat API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create an invoice fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single invoice is created.

To perform an idempotent request, provide an additional idempotency_key element to the request headers. curl header syntax is the following: Idempotency-Key: <key>

How you create unique keys is completely up to you. We suggest using random strings or UUIDs. We’ll always send back the same response for requests made with the same key. However, you cannot use the same key with different request parameters. The keys expire after 24 hours.

Customers

The customer object

Example object

{
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "contact@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": null,
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": [
      {
        "id": "oc_ps_1459584112d83k4ef3e3bd",
        "object": "payment_source",
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "source": "card_1029383qsfqs",
        "payment_source_type": "Credit Card",
        "details": {},
        "country": "FR",
        "exp_month": 12,
        "exp_year": 2017
      }
    ]
  }
}

Customer objects are required to create other Octobat objects such as invoices or transactions that must be attached to them. The API allows you to create, and update your customers. You can retrieve individual customers as well as a list of all your customers.

Attributes

id
string

-

object
string, value is “customer

-

livemode
boolean

-

name
string

Customer’s name.

email
string

Customer’s email.

phone_number
string

Customer’s phone number.

billing_address_line1
string

Customer’s address 1.

billing_address_line2
string

Customer’s address 2.

billing_address_city
string

Customer’s city.

billing_address_zip
string

Customer’s zip code.

billing_address_state
string

Customer’s state.

billing_address_country
string

Two-letter ISO code representing the customer’s country.

business_type
string

The business_type of the customer is either B2B or B2C. Individuals or non-tax-registered companies must be tagged as `B2C` while tax-registered businesses must be tagged as `B2B`.

tax_number
string

If your customer is a business registered at EU-VAT, its VAT registration number.

octobat_billing_page
string

The url of a page listing all customer’s invoices, and where she can edit her billing details

sources
array

References to the integration’s objects this customer has been created from

payment_sources
json

Contains a list of means of payment attached to the customer.

Create a customer

# Definition
POST https://apiv2.octobat.com/customers
# Example Request
$ curl https://apiv2.octobat.com/customers \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d email="contact@octobat.com" \
   -d name="Octobat Inc." \
   -d phone_number="+33 9 52 54 03 70" \
   -d billing_address_zip="75004" \
   -d billing_address_city="Paris" \
   -d billing_address_country="France" \
   -d business_type="B2B" \
   -d tax_number="FR60528551658"

# Example response
{
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "contact@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": "FR60528551658",
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": []
  }
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Customer.create(
  name: "Octobat Inc.",
  email: "contact@octobat.com",
  phone_number: "+33 9 52 54 03 70",
  billing_address_line1: null,
  billing_address_line2: null,
  billing_address_city: "Paris",
  billing_address_zip: "75004",
  billing_address_state: null,
  billing_address_country: "France",
  business_type: "B2B",
  tax_number: "FR60528551658"
)

# Example response
#<Octobat::Customer id=oc_cu_1421878635hksc26e4de79 0x00000a> JSON: {
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "admin@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": "FR60528551658",
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": []
  }
}

Arguments

name
optional

Customer’s name.

email
optional

Customer’s email.

phone_number
optional

Customer’s phone number.

billing_address_line1
optional

Customer’s address 1.

billing_address_line2
optional

Customer’s address 2.

billing_address_city
optional

Customer’s city.

billing_address_zip
optional

Customer’s zip code.

billing_address_state
optional

Customer’s state.

billing_address_country
required

Two-letter ISO code representing the customer’s country.

business_type
optional

The business_type of the customer is either B2B or B2C. An individual must be tagged as `B2C` while a business must be tagged as `B2B`.
If the tax_number and the business_type are not filled, the business_type will be filled to `B2C`.

tax_number
optional

If your customer is a business registered at EU-VAT, its VAT registration number.

Returns

Returns the customer object if the creation succeeds. Returns an error if parameters are invalid

Retrieve a customer

# Definition
GET https://apiv2.octobat.com/customers/{CUSTOMER_ID}

# Example Request
$ curl https://apiv2.octobat.com/customers/oc_cu_1421878635hksc26e4de79 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "contact@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": null,
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": [
      {
        "id": "oc_ps_1459584112d83k4ef3e3bd",
        "object": "payment_source",
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "source": "card_1029383qsfqs",
        "payment_source_type": "Credit Card",
        "details": {},
        "country": "FR",
        "exp_month": 12,
        "exp_year": 2017
      }
    ]
  }
}
# Definition
Octobat::Customer.retrieve({CUSTOMER_ID})

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Customer.retrieve("oc_cu_1421878635hksc26e4de79")

# Example response
#<Octobat::Customer id=oc_cu_1421878635hksc26e4de79 0x00000a> JSON: {
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "contact@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": null,
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": [
      {
        "id": "oc_ps_1459584112d83k4ef3e3bd",
        "object": "payment_source",
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "source": "card_1029383qsfqs",
        "payment_source_type": "Credit Card",
        "details": {},
        "country": "FR",
        "exp_month": 12,
        "exp_year": 2017
      }
    ]
  }
}

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

Arguments

customer
required

The identifier of the customer to be retrieved.

Returns

Returns a customer object if a valid identifier was provided.

Update a customer

# Definition
PATCH https://apiv2.octobat.com/customers/{CUSTOMER_ID}

# Example request
$ curl https://apiv2.octobat.com/customers/oc_cu_1421878635hksc26e4de79 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d email="admin@octobat.com"

# Example response
{
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "admin@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": null,
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": [
      {
        "id": "oc_ps_1459584112d83k4ef3e3bd",
        "object": "payment_source",
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "source": "card_1029383qsfqs",
        "payment_source_type": "Credit Card",
        "details": {},
        "country": "FR",
        "exp_month": 12,
        "exp_year": 2017
      }
    ]
  }
}
# Definition
customer = Octobat::Customer.retrieve({CUSTOMER_ID})
customer.email = {NEW_EMAIL}
customer.save

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

customer = Octobat::Customer.retrieve("oc_cu_1421878635hksc26e4de79")
customer.email = "admin@octobat.com"
customer.save

# Example response
#<Octobat::Customer id=oc_cu_1421878635hksc26e4de79 0x00000a> JSON: {
  "id": "oc_cu_1421878635hksc26e4de79",
  "object" : "customer",
  "livemode" : true,
  "name": "Octobat Inc.",
  "email": "admin@octobat.com",
  "phone_number": "+33 9 52 54 03 70",
  "billing_address_line1": null,
  "billing_address_line2": null,
  "billing_address_city": "Paris",
  "billing_address_zip": "75004",
  "billing_address_state": null,
  "billing_address_country": "France",
  "business_type": "B2B",
  "tax_number": null,
  "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
  "sources": [],
  "payment_sources" : {
    "object": "list",
    "data": [
      {
        "id": "oc_ps_1459584112d83k4ef3e3bd",
        "object": "payment_source",
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "source": "card_1029383qsfqs",
        "payment_source_type": "Credit Card",
        "details": {},
        "country": "FR",
        "exp_month": 12,
        "exp_year": 2017
      }
    ]
  }
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the customer creation call.

Arguments

name
optional

Customer’s name.

email
optional

Customer’s email.

phone_number
optional

Customer’s phone number.

billing_address_line1
optional

Customer’s address 1.

billing_address_line2
optional

Customer’s address 2.

billing_address_city
optional

Customer’s city.

billing_address_zip
optional

Customer’s zip code.

billing_address_state
optional

Customer’s state.

billing_address_country
required

Two-letter ISO code representing the customer’s country.

business_type
optional

The business_type of the customer is either B2B or B2C. An individual must be tagged as `B2C` while a business must be tagged as `B2B`.

tax_number
optional

If your customer is a business registered at EU-VAT, its VAT registration number.

Returns

Returns the customer object if the update succeeded. Returns an error if update parameters are invalid

List all customers

# Definition
GET https://apiv2.octobat.com/customers/

# Example request
$ curl https://apiv2.octobat.com/customers \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_cu_1421878635hksc26e4de79",
      "object" : "customer",
      "livemode" : true,
      "name": "Octobat Inc.",
      "email": "admin@octobat.com",
      "phone_number": "+33 9 52 54 03 70",
      "billing_address_line1": null,
      "billing_address_line2": null,
      "billing_address_city": "Paris",
      "billing_address_zip": "75004",
      "billing_address_state": null,
      "billing_address_country": "France",
      "business_type": "B2B",
      "tax_number": null,
      "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
      "sources": [],
      "payment_sources" : {
        "object": "list",
        "data": [
          {
            "id": "oc_ps_1459584112d83k4ef3e3bd",
            "object": "payment_source",
            "customer": "oc_cu_1459413729au6o6a9ae061",
            "source": "card_1029383qsfqs",
            "payment_source_type": "Credit Card",
            "details": {},
            "country": "FR",
            "exp_month": 12,
            "exp_year": 2017
          }
        ]
      }
    },
    {...},
    {...}
  ]
}
# Definition
Octobat::Customer.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Customer.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::Customer id=oc_cu_1421878635hksc26e4de79 0x00000a> JSON: {
      "id": "oc_cu_1421878635hksc26e4de79",
      "object": "customer",
      "livemode" : true,
      "name": "Octobat Inc.",
      "email": "admin@octobat.com",
      "phone_number": "+33 9 52 54 03 70",
      "billing_address_line1": null,
      "billing_address_line2": null,
      "billing_address_city": "Paris",
      "billing_address_zip": "75004",
      "billing_address_state": null,
      "billing_address_country": "France",
      "business_type": "B2B",
      "tax_number": null,
      "octobat_billing_page": "https://repo.octobat.com/c/1421878635hksc26e4de79",
      "sources": [],
      "payment_sources" : {
        "object": "list",
        "data": [
          {
            "id": "oc_ps_1459584112d83k4ef3e3bd",
            "object": "payment_source",
            "customer": "oc_cu_1459413729au6o6a9ae061",
            "source": "card_1029383qsfqs",
            "payment_source_type": "Credit Card",
            "details": {},
            "country": "FR",
            "exp_month": 12,
            "exp_year": 2017
          }
        ]
      }
    },
    #<Octobat::Customer[...] ...>,
    #<Octobat::Customer[...] ...>
  ]
}

Returns a list of your customers.

Returns

A hash with a data property that contains an array of customers. Each entry in the array is a separate customer object. If no customers are available, the resulting array will be empty. This request should never raise an error.

Invoices

The invoice object

Example object

{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "paid",
  "status": "confirmed",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "en",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": null,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": null,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-04-26",
        "transaction": null,
        "transaction": null,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": null,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "IT",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}

Attributes

id
string

-

object
string, value is “invoice

-

livemode
boolean

-

customer
string

ID of the customer.

invoice_numbering_sequence
string

ID of the invoice numbering sequence.

document_template
string

ID of the document template.

payment_recipients
array

IDs of payment recipients.

pdf_file_url
string

URL of the invoice PDF.

invoice_number
string

Autocalculate number of the invoice.

invoice_date
string

Date of the invoice.

description
string

-

payment_status
string

The payment status of the invoice is either paid or unpaid.

status
string

The status of the invoice is either draft, confirmed or cancelled.

email_sent
boolean

If email is sent to the customer or not.

last_sent_at
string

Sending date if email has been sent.

notes
string

-

language
string

Invoice’s language.

currency
string

Invoice’s currency.

legal_fields
json

Fields depending on the supplier country.

cancel_and_replace_invoice
string

ID of the invoice cancelled and replaced by this invoice.

sources
array

References to the integration’s objects this invoice has been created from.

items
list

Invoice items.

Create an invoice

# Definition
POST https://apiv2.octobat.com/invoices

# Example request
$ curl https://apiv2.octobat.com/invoices \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_1459413729au6o6a9ae061" \
   -d payment_recipients[]="oc_pr_1461595230igdu5ce59471" \
   -d payment_recipients[]="oc_pr_14603917916fhf5eb09a69" \
   -d description='Subscription' \
   -d currency='EUR' \
   -d notes='' \


# Example response
{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": null,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": null
  "sources": [],
  "items": {"object"=>"list", "data"=>[]}
}
# Definition
POST https://apiv2.octobat.com/invoices

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Invoice.create(
  customer: "oc_cu_1459413729au6o6a9ae061",
  payment_recipients: ['oc_pr_14603917916fhf5eb09a69', 'oc_pr_1461595230igdu5ce59471'],
  description: 'Subscription',
  currency: 'EUR',
  notes: ''
)

# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": nil,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": nil,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": nil,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "cancel_and_replace_invoice": nil,
  "sources": [],
  "items": {"object"=>"list", "data"=>[]}
}

To create an invoice for a customer, you must first create it as a draft. Then, you must add items upon it, add payments, and declare if it still has to be paid or if the payment has already been performed.

Arguments

customer
required

The ID of an existing customer.

payment_recipients
required

The IDs of existing payment recipients.

currency
required

Three-letter ISO code representing the currency of the transaction.

invoice_numbering_sequence
optional

Numbering sequence ID. Fallbacks to default numbering sequence if not filled.

description
optional

Invoice’s description.

notes
optional

What you want display at the end of the invoice.

Returns

Returns the full invoice object if the creation succeeded. Returns an error if parameters are invalid

Update a draft invoice

# Definition
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}

# Example request
$ curl https://apiv2.octobat.com/invoices/oc_in_1461320056h2qq350fdc3a \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer_name="Zuuno SARL" \
   -d customer_business_type="B2B" \
   -d customer_tax_number="FR60528551658" \


# Example response
{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": null,
  "sources": [],
  "items": {"object"=>"list", "data"=>[]}
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.customer_name = {NEW_CUSTOMER_NAME}
invoice.customer_business_type = {NEW_CUSTOMER_BUSINESS_TYPE}
invoice.customer_tax_number = {NEW_CUSTOMER_TAX_NUMBER}
invoice.save

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1461320056h2qq350fdc3a")
invoice.customer_name = "Zuuno SARL"
invoice.customer_business_type = "B2B"
invoice.customer_tax_number = "FR60528551658"
invoice.save


# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": nil,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": nil,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "cancel_and_replace_invoice": nil,
  "sources": [],
  "items": {"object"=>"list", "data"=>[]}
}

Arguments

customer_name
optional

-

customer_address_line_1
optional

-

customer_address_line_2
optional

-

customer_address_city
optional

-

customer_address_state
optional

-

customer_address_zip
optional

-

customer_address_country
optional

-

customer_tax_number
optional

-

customer_business_type
optional

-

description
optional

-

notes
optional

-

Returns

Returns the full invoice object if the update succeeded. Returns an error if the invoice has already been sent by email and is no longer updatable, or if the update fails

Send by email

# Definition
POST https://apiv2.octobat.com/invoices/{INVOICE_ID}/send

# Example request


# Example response

# Definition
invoice = Octobat::Invoice.retrieve("oc_in_14234251141rdhb20d40fe")
invoice.send()

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_14234251141rdhb20d40fe")
invoice.send

# Example response
#<Octobat::Invoice id=oc_in_14234251141rdhb20d40fe 0x00000a> JSON: {{
  "id": "oc_in_14234251141rdhb20d40fe",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": "https://www.octobat.com/invoices/oc_in_14234251141rdhb20d40fe.pdf",
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "confirmed",
  "email_sent": true,
  "last_sent_at": "2016-08-17T16:01:37Z",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "cancel_and_replace_invoice": nil,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-08-12",
        "transaction": nil,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": nil,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Arguments

email_to
optional

Email receiver.

email_title
optional

Email title.

Returns

Returns the full invoice object if the sending succeeded. Returns an error if the invoice customer email is empty or if the invoice hasn’t a confirmed status.

Confirm a draft invoice

# Definition
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}/confirm

# Example request
curl https://www.octobat.com/invoices/oc_in_1461320056h2qq350fdc3a/confirm \
 -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
 -X PATCH

# Example response
{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "confirmed",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": null,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-04-26",
        "transaction": null,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": null,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.confirm

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1461320056h2qq350fdc3a")
invoice.confirm()

# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": nil,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "confirmed",
  "email_sent": false,
  "last_sent_at": nil,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "cancel_and_replace_invoice": nil,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-04-26",
        "transaction": nil,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": nil,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Returns

After creating a draft invoice and adding invoice items, you have to confirm it before sending it to the customer. At least one item must have attached to the invoice. Returns the full invoice object if the update succeeded. Returns an error if update parameters are invalid.

Cancel a confirmed invoice

# Definition
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}/cancel

# Example request
curl https://www.octobat.com/invoices/oc_in_1461320056h2qq350fdc3a/cancel \
 -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
 -X PATCH

# Example response
{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "cancelled",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": null,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "cancelled",
        "confirmed_on": "2016-04-26",
        "transaction": null,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": null,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.cancel

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1461320056h2qq350fdc3a")
invoice.cancel()

# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": nil,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "cancelled",
  "email_sent": false,
  "last_sent_at": nil,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "cancel_and_replace_invoice": nil,
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "cancelled",
        "confirmed_on": "2016-04-26",
        "transaction": nil,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": nil,
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Change the invoice status to ‘cancelled’ and create a credit note with invoice items duplicated.

Returns

Returns the full invoice object if the update succeeded. Returns an error if update parameters are invalid.

Cancel and replace a confirmed invoice

# Definition
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}/cancel_and_replace

# Example request
curl https://www.octobat.com/invoices/oc_in_1476088610jx98e4b8b8d3/cancel_and_replace \
 -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
 -X PATCH

# Example response
{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": null,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": null,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "cancel_and_replace_invoice": "oc_in_1476088610jx98e4b8b8d3",
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "draft",
        "confirmed_on": null,
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "transaction": null,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": null,
        "product_type": "standard",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.cancel_and_replace

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1476088610jx98e4b8b8d3")
invoice.cancel_and_replace()

# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {{
  "id": "oc_in_1461320056h2qq350fdc3a",
  "object": "invoice",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
  "pdf_file_url": nil,
  "invoice_number": "SP2016-200",
  "invoice_date": "2016-04-26",
  "description": "Subscription",
  "payment_status": "unpaid",
  "status": "draft",
  "email_sent": false,
  "last_sent_at": nil,
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": "FR60528551658",
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "sources": [],
  "cancel_and_replace_invoice": "oc_in_1476088610jx98e4b8b8d3",
  "items": {
    "object":"list",
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "draft",
        "confirmed_on": nil,
        "customer": "oc_cu_1459413729au6o6a9ae061",
        "transaction": nil,
        "invoice": "oc_in_1461320056h2qq350fdc3a",
        "credit_note": nil,
        "product_type": "standard",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Change the invoice status to ‘cancelled’, create a credit note with invoice items duplicated and create a new invoice with a ‘draft’ status and the same attributes than the ‘cancelled’ invoice.

Returns

Returns the full ‘draft’ new invoice object if the cancel and replace succeeded. Returns an error if the cancel and replace action is not possible.

Delete a draft invoice

# Definition
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}

# Example request
curl https://www.octobat.com/invoices/oc_in_1461320056h2qq350fdc3a \
 -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
 -X DELETE

# Example response
{
  "deleted": true,
  "id": "oc_in_1461320056h2qq350fdc3a"
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.delete

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1461320056h2qq350fdc3a")
invoice.delete

# Example response
#<Octobat::Invoice id=oc_in_1461320056h2qq350fdc3a 0x00000a> JSON: {{
  "deleted": true,
  "id": "oc_in_1461320056h2qq350fdc3a"
}

You can only delete an invoice with a ‘draft’ status.

Returns

Returns an object with a deleted parameter on success. If the invoice ID does not exist, this call raises an error.

Record a payment

You can record a payment linked to an invoice creating a transaction with the invoice ID. Go to Record a payment.

List all invoices

# Definition
GET https://apiv2.octobat.com/invoices/

# Example request
$ curl https://apiv2.octobat.com/invoices \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_1459413729au6o6a9ae061" \
   -d status="draft" \
   -d starting_after='oc_in_14611572304z2g1db98a0b' \


# Example response
{
  "object": "list",
  "has_before": true,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_in_1461320056h2qq350fdc3a",
      "object": "invoice",
      "livemode": true,
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
      "document_template": "oc_dt_14611418085kha558d6ddf",
      "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
      "pdf_file_url": null,
      "invoice_number": "SP2016-200",
      "invoice_date": "2016-04-26",
      "description": "Subscription",
      "payment_status": "unpaid",
      "status": "draft",
      "email_sent": false,
      "last_sent_at": null,
      "notes": "",
      "language": "fr",
      "currency": "EUR",
      "customer_name": "John doe",
      "customer_address_line_1": "25 rue du Petit Musc",
      "customer_address_line_2": null,
      "customer_address_city": "Paris",
      "customer_address_state": null,
      "customer_address_zip": "75004",
      "customer_address_country": "France",
      "customer_country_code": "FR",
      "customer_tax_number": null,
      "customer_business_type": "B2C",
      "supplier_name": "Octobat SAS",
      "supplier_address_line_1": "230 rue du Général Leclerc",
      "supplier_address_line_2": "",
      "supplier_address_city": "Ermont",
      "supplier_address_state": null,
      "supplier_address_zip": "95120",
      "supplier_address_country": "France",
      "supplier_tax_number": null,
      "legal_fields": {},
      "sources": [],
      "cancel_and_replace_invoice": null,
      "items": {
        "object":"list",
        "data": [
          {
            "id": "oc_it_146133143279h39ba598f5",
            "object": "item",
            "status": "draft",
            "confirmed_on": null,
            "transaction": null,
            "invoice": "oc_in_1461320056h2qq350fdc3a",
            "credit_note": null,
            "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
            "product_type": "eservice",
            "sale_mode": "B2C",
            "description": "Entreprise Plan",
            "unit_extratax_amount": 19900,
            "currency": "EUR",
            "quantity": 1,
            "extratax_amount": 19900,
            "tax_rate": 22.0,
            "tax_amount": 4378,
            "gross_amount": 24278,
            "declare_in_region": "FR",
            "tax": "VAT",
            "sources": [],
            "item_exchange": null,
            "item_workspace_currency_exchange": null
          },
          {...},
          {...}
        ]
      }
    },
    {...},
    {...}
  ]
}
# Definition
GET https://apiv2.octobat.com/invoices

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Invoice.all(
  customer: "oc_cu_1459413729au6o6a9ae061",
  status: "draft",
  starting_after: 'oc_in_14611572304z2g1db98a0b'
)

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": true,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_in_1461320056h2qq350fdc3a",
      "object": "invoice",
      "livemode": true,
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "invoice_numbering_sequence": "oc_ns_146192091741t5175c8c47",
      "document_template": "oc_dt_14611418085kha558d6ddf",
      "payment_recipients": ["oc_pr_14603917916fhf5eb09a69", "oc_pr_1461595230igdu5ce59471"],
      "pdf_file_url": nil,
      "invoice_number": "SP2016-200",
      "invoice_date": "2016-04-26",
      "description": "Subscription",
      "payment_status": "unpaid",
      "status": "draft",
      "email_sent": false,
      "last_sent_at": nil,
      "notes": "",
      "language": "fr",
      "currency": "EUR",
      "customer_name": "John doe",
      "customer_address_line_1": "25 rue du Petit Musc",
      "customer_address_line_2": nil,
      "customer_address_city": "Paris",
      "customer_address_state": nil,
      "customer_address_zip": "75004",
      "customer_address_country": "France",
      "customer_country_code": "FR",
      "customer_tax_number": nil,
      "customer_business_type": "B2C",
      "supplier_name": "Octobat SAS",
      "supplier_address_line_1": "230 rue du Général Leclerc",
      "supplier_address_line_2": "",
      "supplier_address_city": "Ermont",
      "supplier_address_state": nil,
      "supplier_address_zip": "95120",
      "supplier_address_country": "France",
      "supplier_tax_number": nil,
      "legal_fields": {},
      "cancel_and_replace_invoice": nil,
      "sources": [],
      "items": {
        "object":"list",
        "data": [
          {
            "id": "oc_it_146133143279h39ba598f5",
            "object": "item",
            "status": "draft",
            "confirmed_on": nil,
            "transaction": nil,
            "invoice": "oc_in_1461320056h2qq350fdc3a",
            "credit_note": nil,
            "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
            "product_type": "eservice",
            "sale_mode": "B2C",
            "description": "Entreprise Plan",
            "unit_extratax_amount": 19900,
            "currency": "EUR",
            "quantity": 1,
            "extratax_amount": 19900,
            "tax_rate": 22.0,
            "tax_amount": 4378,
            "gross_amount": 24278,
            "declare_in_region": "FR",
            "tax": "VAT",
            "sources": [],
            "item_exchange": nil,
            "item_workspace_currency_exchange": nil
          },
          {...},
          {...}
        ]
      }
    },
    {...},
    {...}
  ]
}

Returns a list of invoices.

Arguments

customer
optional

The ID of an existing customer.

status
optional

The status of the invoice is either draft or confirmed.

starting_after
optional

Starting after an invoice id.

ending_before
optional

Ending before an invoice id.

invoice_date[gte]
optional

Greater than or equal to a date.

invoice_date[lte]
optional

Lower than or equal to a date.

Returns

A hash with a data property that contains an array of invoices. Each entry in the array is a separate invoice object. If no invoices are available, the resulting array will be empty. This request should never raise an error.

Credit notes

The credit note object

Example object

{
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": null,
  "pdf_file_url": null,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": false,
  "last_sent_at": null,
  "status": "confirmed",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": null,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-05-03",
        "transaction": null,
        "invoice": null,
        "credit_note": "oc_cn_1462279788aw2y99365ac5",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}

Attributes

id
string

-

object
string, value is “credit_note

-

livemode
boolean

-

customer
string

ID of the customer.

credit_note_numbering_sequence
string

ID of the credit_note numbering sequence.

document_template
string

ID of the document template.

invoice
string

ID of the invoice.

pdf_file_url
string

URL of the credit note PDF.

credit_note_number
string

Autocalculate number of the credit note.

credit_note_date
string

Date of the credit note.

description
string

-

payment_status
string

The payment status of the credit note is either refunded or te refund.

status
string

The status of the credit note is either draft, confirmed or cancelled.

email_sent
boolean

If email is sent to the customer or not.

last_sent_at
string

Sending date if email has been sent.

notes
string

-

language
string

Credit note’s language.

currency
string

Credit note’s currency.

legal_fields
json

Fields depending on the supplier country.

sources
array

References to the integration’s objects this credit note has been created from.

items
list

Credit note items.

Create a credit note

# Definition
POST https://apiv2.octobat.com/credit_notes

# Example request
$ curl https://apiv2.octobat.com/credit_notes \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_1459413729au6o6a9ae061" \
   -d description='Refund Subscription' \
   -d currency='EUR' \
   -d notes='' \


# Example response
{
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": null,
  "pdf_file_url": null,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": false,
  "last_sent_at": null,
  "status": "draft",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": null,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": null,
  "legal_fields": {},
  "sources": [],
  "items": {
    "object":"list",
    "data": []
  }
}
# Definition
POST https://apiv2.octobat.com/credit_notes

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::CreditNote.create(
  customer: "oc_cu_1459413729au6o6a9ae061",
  description: 'Refund Subscription',
  currency: 'EUR',
  notes: ''
)

# Example response
#<Octobat::CreditNote id=oc_cn_1462279788aw2y99365ac5 0x00000a> JSON: {
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": nil,
  "pdf_file_url": nil,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": false,
  "last_sent_at": nil,
  "status": "draft",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "John doe",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": nil,
  "customer_business_type": "B2C",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": nil,
  "legal_fields": {},
  "sources": [],
  "items": {
    "object":"list",
    "data": []
  }
}

Arguments

customer
required

The ID of an existing customer.

currency
required

Three-letter ISO code representing the currency of the transaction.

credit_note_numbering_sequence
optional

Numbering sequence ID. Fallbacks to default numbering sequence if not filled.

invoice
optional

Invoice ID. The credit note is linked to this invoice.

description
optional

Credit note’s description.

notes
optional

What you want display at the end of the credit note.

Returns

Returns the full credit note object if the creation succeeded. Returns an error if parameters are invalid.

Update a credit note

# Definition
PATCH https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}

# Example request
$ curl https://apiv2.octobat.com/credit_notes/oc_cn_1462279788aw2y99365ac5 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer_name="Zuuno SARL" \
   -d customer_business_type="B2B" \
   -d customer_tax_number="FR60528551658" \


# Example response
{
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": null,
  "pdf_file_url": null,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": false,
  "last_sent_at": null,
  "status": "confirmed",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": null,
  "customer_address_city": "Paris",
  "customer_address_state": null,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": null,
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": null,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": "FR60528551658",
  "legal_fields": {},
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-05-03",
        "transaction": null,
        "invoice": null,
        "credit_note": "oc_cn_1462279788aw2y99365ac5",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": null,
        "item_workspace_currency_exchange": null
      },
      {...},
      {...}
    ]
  }
}
# Definition
credit_note = Octobat::CreditNote.retrieve({CREDIT_NOTE_ID})
credit_note.customer_name = {NEW_CUSTOMER_NAME}
credit_note.customer_business_type = {NEW_CUSTOMER_BUSINESS_TYPE}
credit_note.customer_tax_number = {NEW_CUSTOMER_TAX_NUMBER}
credit_note.save

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

credit_note = Octobat::CreditNote.retrieve("oc_cn_1462279788aw2y99365ac5")
credit_note.customer_name = "Zuuno SARL"
credit_note.customer_business_type = "B2B"
credit_note.customer_tax_number = "FR60528551658"
credit_note.save


# Example response
#<Octobat::CreditNote id=oc_cn_1462279788aw2y99365ac5 0x00000a> JSON: {
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": nil,
  "pdf_file_url": nil,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": false,
  "last_sent_at": nil,
  "status": "confirmed",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": nil,
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": "FR60528551658",
  "legal_fields": {},
  "sources": [],
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2016-05-03",
        "transaction": nil,
        "invoice": nil,
        "credit_note": "oc_cn_1462279788aw2y99365ac5",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Arguments

customer_name
optional

-

customer_address_line_1
optional

-

customer_address_line_2
optional

-

customer_address_city
optional

-

customer_address_state
optional

-

customer_address_zip
optional

-

customer_address_country
optional

-

customer_tax_number
optional

-

customer_business_type
optional

-

description
optional

-

notes
optional

-

Returns

Returns the full credit note object if the update succeeded. Returns an error if the credit note has already been sent by email and is no longer updatable, or if the update fails.

Send by email

# Definition
POST https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}/send

# Example request


# Example response

# Definition
credit_note = Octobat::CreditNote.retrieve("oc_cn_1462279788aw2y99365ac5")
credit_note.send()

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

credit_note = Octobat::CreditNote.retrieve("oc_cn_1462279788aw2y99365ac5")
credit_note.send

# Example response
#<Octobat::CreditNote id=oc_cn_1462279788aw2y99365ac5 0x00000a> JSON: {{
  "id": "oc_cn_1462279788aw2y99365ac5",
  "object": "credit_note",
  "livemode": true,
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
  "document_template": "oc_dt_14611418085kha558d6ddf",
  "invoice": nil,
  "pdf_file_url": nil,
  "credit_note_number": "CN-AAA-2",
  "credit_note_date": "2016-05-03",
  "description": "Refund Subscription",
  "email_sent": true,
  "last_sent_at": "2016-08-17T16:01:37Z",
  "status": "confirmed",
  "payment_status": "to refund",
  "notes": "",
  "language": "fr",
  "currency": "EUR",
  "customer_name": "Zuuno SARL",
  "customer_address_line_1": "25 rue du Petit Musc",
  "customer_address_line_2": nil,
  "customer_address_city": "Paris",
  "customer_address_state": nil,
  "customer_address_zip": "75004",
  "customer_address_country": "France",
  "customer_country_code": "FR",
  "customer_tax_number": nil,
  "customer_business_type": "B2B",
  "supplier_name": "Octobat SAS",
  "supplier_address_line_1": "230 rue du Général Leclerc",
  "supplier_address_line_2": "",
  "supplier_address_city": "Ermont",
  "supplier_address_state": nil,
  "supplier_address_zip": "95120",
  "supplier_address_country": "France",
  "supplier_tax_number": "FR60528551658",
  "sources": [],
  "legal_fields": {},
  "items": {
    "object":"list",
    "data": [
      {
        "id": "oc_it_146133143279h39ba598f5",
        "object": "item",
        "status": "confirmed",
        "confirmed_on": "2015-05-03",
        "transaction": nil,
        "invoice": nil,
        "credit_note": "oc_cn_1462279788aw2y99365ac5",
        "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
        "product_type": "eservice",
        "sale_mode": "B2C",
        "description": "Entreprise Plan",
        "unit_extratax_amount": 19900,
        "currency": "EUR",
        "quantity": 1,
        "extratax_amount": 19900,
        "tax_rate": 22.0,
        "tax_amount": 4378,
        "gross_amount": 24278,
        "declare_in_region": "FR",
        "tax": "VAT",
        "sources": [],
        "item_exchange": nil,
        "item_workspace_currency_exchange": nil
      },
      {...},
      {...}
    ]
  }
}

Arguments

email_to
optional

Email receiver.

email_title
optional

Email title.

Returns

Returns the full credit note object if the sending succeeded. Returns an error if the credit note customer email is empty or if the credit note hasn’t a confirmed status.

Record a refund

You can record a refund linked to a credit note creating a transaction with the credit note ID. Go to Record a refund.

List all credit notes

# Definition
GET https://apiv2.octobat.com/credit_notes/

# Example request
$ curl https://apiv2.octobat.com/credit_notes \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_1459413729au6o6a9ae061" \


# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_cn_1462279788aw2y99365ac5",
      "object": "credit_note",
      "livemode": true,
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
      "document_template": "oc_dt_14611418085kha558d6ddf",
      "invoice": null,
      "pdf_file_url": null,
      "credit_note_number": "CN-AAA-2",
      "credit_note_date": "2016-05-03",
      "description": "Refund Subscription",
      "email_sent": false,
      "last_sent_at": null,
      "status": "confirmed",
      "payment_status": "to refund",
      "notes": "",
      "language": "fr",
      "currency": "EUR",
      "customer_name": "John doe",
      "customer_address_line_1": "25 rue du Petit Musc",
      "customer_address_line_2": null,
      "customer_address_city": "Paris",
      "customer_address_state": null,
      "customer_address_zip": "75004",
      "customer_address_country": "France",
      "customer_country_code": "FR",
      "customer_tax_number": null,
      "customer_business_type": "B2C",
      "supplier_name": "Octobat SAS",
      "supplier_address_line_1": "230 rue du Général Leclerc",
      "supplier_address_line_2": "",
      "supplier_address_city": "Ermont",
      "supplier_address_state": null,
      "supplier_address_zip": "95120",
      "supplier_address_country": "France",
      "supplier_tax_number": null,
      "legal_fields": {},
      "sources": [],
      "items": {
        "object":"list",
        "data": [
          {
            "id": "oc_it_146133143279h39ba598f5",
            "object": "item",
            "status": "confirmed",
            "confirmed_on": "2016-05-03",
            "transaction": null,
            "invoice": null,
            "credit_note": "oc_cn_1462279788aw2y99365ac5",
            "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
            "product_type": "eservice",
            "sale_mode": "B2C",
            "description": "Entreprise Plan",
            "unit_extratax_amount": 19900,
            "currency": "EUR",
            "quantity": 1,
            "extratax_amount": 19900,
            "tax_rate": 22.0,
            "tax_amount": 4378,
            "gross_amount": 24278,
            "declare_in_region": "FR",
            "tax": "VAT",
            "sources": [],
            "item_exchange": null,
            "item_workspace_currency_exchange": null
          },
          {...},
          {...}
        ]
      }
    },
    {...},
    {...}
  ]
}
# Definition
GET https://apiv2.octobat.com/credit_notes

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::CreditNote.all(
  customer: "oc_cu_1459413729au6o6a9ae061"
)

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_cn_1462279788aw2y99365ac5",
      "object": "credit_note",
      "livemode": true,
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "credit_note_numbering_sequence": "oc_cns_1462279395ko79c927206e",
      "document_template": "oc_dt_14611418085kha558d6ddf",
      "invoice": nil,
      "pdf_file_url": nil,
      "credit_note_number": "CN-AAA-2",
      "credit_note_date": "2016-05-03",
      "description": "Refund Subscription",
      "email_sent": false,
      "last_sent_at": nil,
      "status": "confirmed",
      "payment_status": "to refund",
      "notes": "",
      "language": "fr",
      "currency": "EUR",
      "customer_name": "John doe",
      "customer_address_line_1": "25 rue du Petit Musc",
      "customer_address_line_2": nil,
      "customer_address_city": "Paris",
      "customer_address_state": nil,
      "customer_address_zip": "75004",
      "customer_address_country": "France",
      "customer_country_code": "FR",
      "customer_tax_number": nil,
      "customer_business_type": "B2C",
      "supplier_name": "Octobat SAS",
      "supplier_address_line_1": "230 rue du Général Leclerc",
      "supplier_address_line_2": "",
      "supplier_address_city": "Ermont",
      "supplier_address_state": nil,
      "supplier_address_zip": "95120",
      "supplier_address_country": "France",
      "supplier_tax_number": nil,
      "legal_fields": {},
      "sources": [],
      "items": {
        "object":"list",
        "data": [
          {
            "id": "oc_it_146133143279h39ba598f5",
            "object": "item",
            "status": "confirmed",
            "confirmed_on": "2016-05-03",
            "transaction": nil,
            "invoice": nil,
            "credit_note": "oc_cn_1462279788aw2y99365ac5",
            "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
            "product_type": "eservice",
            "sale_mode": "B2C",
            "description": "Entreprise Plan",
            "unit_extratax_amount": 19900,
            "currency": "EUR",
            "quantity": 1,
            "extratax_amount": 19900,
            "tax_rate": 22.0,
            "tax_amount": 4378,
            "gross_amount": 24278,
            "declare_in_region": "FR",
            "tax": "VAT",
            "sources": [],
            "item_exchange": nil,
            "item_workspace_currency_exchange": nil
          },
          {...},
          {...}
        ]
      }
    },
    {...},
    {...}
  ]
}

Returns a list of credit notes.

Arguments

customer
optional

The ID of an existing customer.

invoice
optional

The ID of an existing invoice.

starting_after
optional

Starting after an credit note id.

ending_before
optional

Ending before an credit note id.

credit_note_date[gte]
optional

Greater than or equal to a date.

credit_note_date[lte]
optional

Lower than or equal to a date.

Returns

A hash with a data property that contains an array of credit notes. Each entry in the array is a separate credit note object. If no credit notes are available, the resulting array will be empty. This request should never raise an error.

Tax evidences

Permit tax automation.

The tax evidence object

Example object

{
  "id": "oc_tev_1476028202copc58f93027",
  "object": "tax_evidence",
  "livemode": false,
  "sale_mode": "B2B",
  "product_type": "eservice",
  "tax_enabled": false,
  "tax": null,
  "tax_zone": null,
  "declare_in_region": null,
  "applied_rate": 0.0,
  "tax_details": null,
  "tax_id_validation": {
    "id": "oc_tvl_1476032361kezn4a74878c",
    "object": "tax_id_validation",
    "tax_id": "FR60528551658",
    "is_valid": true
  },
  "supplier_evidence": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "supplier_localization": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "customer_evidence": {
    "tax_id": "FR60528551658",
    "billing": {
      "zip": "75002",
      "state": null,
      "country": "FR"
    },
    "ip": null,
    "payment_mode": null
  },
  "customer_localization": {
    "country": "FR"
  }
}

Attributes

id
string

-

object
string, value is “tax_evidence

-

livemode
boolean

-

sale_mode
string

Values can be: B2C or B2B.

product_type
string

Values can be: eservice, standard or ebook.

tax_enabled
boolean

-

tax
???

???

tax_zone
???

???

declare_in_region
???

???

applied_rate
float

Tax rate applied to the transaction.

tax_details
???

???

tax_id_validation
hash

PLUSIEURS ATTRIBUTES

supplier_evidence
hash

PLUSIEURS ATTRIBUTES

supplier_localization
hash

PLUSIEURS ATTRIBUTES

customer_evidence
hash

PLUSIEURS ATTRIBUTES

customer_localization
hash

PLUSIEURS ATTRIBUTES

Create a tax evidence

# Definition
POST https://apiv2.octobat.com/tax_evidences
# Example Request
$ curl https://apiv2.octobat.com/tax_evidences \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_14760321296p4b6e6f113e" \
   -d product_type="eservice" \
   -d transaction_date= "2016-10-09"

# Example response
{
  "id": "oc_tev_1476028202copc58f93027",
  "object": "tax_evidence",
  "livemode": false,
  "sale_mode": "B2B",
  "product_type": "eservice",
  "tax_enabled": false,
  "tax": nil,
  "tax_zone": nil,
  "declare_in_region": nil,
  "applied_rate": 0.0,
  "tax_details": nil,
  "tax_id_validation": {
    "id": "oc_tvl_1476032361kezn4a74878c",
    "object": "tax_id_validation",
    "tax_id": "FR60528551658",
    "is_valid": true
  },
  "supplier_evidence": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "supplier_localization": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "customer_evidence": {
    "tax_id": "FR60528551658",
    "billing": {
      "zip": "75002",
      "state": nil,
      "country": "FR"
    },
    "ip": nil,
    "payment_mode": nil
  },
  "customer_localization": {
    "country": "FR"
  }
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::TaxEvidence.create(
  customer: "oc_cu_14760321296p4b6e6f113e",
  product_type: "eservice",
  transaction_date: "2016-10-09"
)

# Example response
#<Octobat::TaxEvidence id=oc_tev_1476028202copc58f93027 0x00000a> JSON: {
  "id": "oc_tev_1476028202copc58f93027",
  "object": "tax_evidence",
  "livemode": false,
  "sale_mode": "B2B",
  "product_type": "eservice",
  "tax_enabled": false,
  "tax": nil,
  "tax_zone": nil,
  "declare_in_region": nil,
  "applied_rate": 0.0,
  "tax_details": nil,
  "tax_id_validation": {
    "id": "oc_tvl_1476032361kezn4a74878c",
    "object": "tax_id_validation",
    "tax_id": "FR60528551658",
    "is_valid": true
  },
  "supplier_evidence": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "supplier_localization": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "customer_evidence": {
    "tax_id": "FR60528551658",
    "billing": {
      "zip": "75002",
      "state": nil,
      "country": "FR"
    },
    "ip": nil,
    "payment_mode": nil
  },
  "customer_localization": {
    "country": "FR"
  }
}

Arguments

customer
required

The ID of an existing customer.

sale_mode
optional, default is the customer business type.

The sale mode is either B2C or B2B.

product_type
optional, default is your product_type setting.

The product type is either eservice, ebook or standard.

transaction_date
optional

Date.

Returns

Returns the tax evidence object if the creation succeeds. Returns an error if parameters are invalid.

Request a tax evidence

# Definition
POST https://apiv2.octobat.com/tax_evidence_requests
# Example Request
$ curl https://apiv2.octobat.com/tax_evidence_requests \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer_billing_address_country="FR" \
   -d ip_address=8.8.8.8
   -d payment_source_type=card
   -d payment_source_prefix=497209
   -d payment_source_country=FR
   -d transaction_date= "2016-10-09"

# Example response
{
  "id": "oc_tev_1476028202copc58f93027",
  "object": "tax_evidence",
  "livemode": false,
  "sale_mode": "B2C",
  "product_type": "eservice",
  "tax_enabled": false,
  "tax": 1,
  "tax_zone": "EU",
  "declare_in_region": "FR",
  "applied_rate": 20.0,
  "tax_details": [{
    "rate": "20.0",
    "tax": "VAT",
    "name": "FR",
    "type": "country",
    "reduced": false
  }],
  "tax_id_validation": null,
  "supplier_evidence": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "supplier_localization": {
    "zip": "94080",
    "state": "California",
    "country": "US"
  },
  "customer_evidence": {
    "tax_id": null,
    "billing": {
      "zip": null,
      "state": null,
      "country": "FR"
    },
    "ip": {
      "address": "8.8.8.8",
      "country": "US"
    },
    "payment_source": {
      "type": "card",
      "prefix": "497209",
      "country": "FR"
    }
  },
  "customer_localization": {
    "country": "FR"
  }
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::TaxEvidenceRequest.create(
  customer_billing_address_country: "FR",
  ip_address: "8.8.8.8",
  payment_source_prefix: "card",
  payment_source_prefix: "497209",
  payment_source_country: "FR"
)

# Example response
#<Octobat::TaxEvidence id=oc_tev_1476028202copc58f93027 0x00000a> JSON: {
  "id": "oc_tev_1476028202copc58f93027",
  "object": "tax_evidence",
  "livemode": false,
  "sale_mode": "B2C",
  "product_type": "eservice",
  "tax_enabled": true,
  "tax": "VAT",
  "tax_zone": "EU",
  "declare_in_region": "FR",
  "applied_rate": 20.0,
  "tax_details": [{
    "rate": "20.0",
    "tax": "VAT",
    "name": "FR",
    "type": "country",
    "reduced": false
  }],
  "tax_id_validation": nil,
  "supplier_evidence": {
    "zip": "",
    "state": "",
    "country": "FR"
  },
  "supplier_localization": {
    "zip": "",
    "state": "",
    "country": "FR"
  },
  "customer_evidence": {
    "tax_id": nil,
    "billing": {
      "zip": "",
      "state": "",
      "country": "FR"
    },
    "ip": {
      "address": "8.8.8.8",
      "country": "FR"
    },
    "payment_source": {
      "type": "card",
      "prefix": "497209",
      "country": "FR"
    }
  },
  "customer_localization": {
    "country": "FR"
  }
}

Use cases

If you want to compute an automatic tax calculation to display the tax rates for a given transaction before it is actually performed, or if the customer doesn’t exist yet in Octobat, you can request a tax evidence from Octobat giving the useful evidence parameters such as customer’s billing address, IP address, tax number, or payment source prefix/country.

Arguments

customer_billing_address_zip
optional

The customer’s billing address zipcode.

customer_billing_address_state
optional

The customer’s billing address state.

customer_billing_address_country
optional

The customer’s billing address country.

customer_tax_number
optional

The customer’s tax number (VAT id in EU).

customer_business_type
optional

Possible values: B2B or B2C. Use it to hardcode the automatic business type detection

product_type
optional

The product type is either eservice, ebook or standard. Defaults to the settings default product type.

ip_address
optional

The IP address used by the customer when making the purchase. Can be formatted as an IPv4 or IPv6.

payment_source_type
optional

The payment source type used to perform the transaction. Possible values: card or bank account or other.

payment_source_prefix
optional

The credit card first 6 digits or IBAN/Bank account prefix. Used as an evidence to detect the payment source country

payment_source_country
optional

Fill it if you know where this payment source is from.

transaction_date
optional

Date.

Returns

Returns the tax evidence object if the creation succeeds. Returns an error if parameters are invalid.

Items

Either attached to a document or a transaction.

The item object

Example object

{
  "id": "oc_it_1460568443g3wu6b48fc3e",
  "object": "item",
  "status": "draft",
  "confirmed_on": null,
  "transaction": "oc_txn_14605672518yko2fd30d23",
  "invoice": null,
  "credit_note": null,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type": "eservice",
  "sale_mode": "B2C",
  "discountable": true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 19900,
  "currency": "USD",
  "quantity": 1,
  "extratax_amount": 19900,
  "tax_rate": 22.0,
  "tax_amount": 4378,
  "gross_amount": 24278,
  "declare_in_region": "IT",
  "tax": "VAT",
  "sources": [],
  "item_exchange": {
    "exchange_rate": 0.8864,
    "exchange_date": "2016-04-13T17:27:24.228Z",
    "exchanged_to_currency": "EUR"
  },
  "item_workspace_currency_exchange": {
    "exchange_rate": 0.9526,
    "exchange_date": "2016-04-11T17:27:24.228Z",
    "exchanged_to_currency": "GBP"
  }
}

Attributes

id
string

-

object
string, value is “item

-

status
string

Depending on the invoice, credit note or transaction status.

confirmed_on
date

If the item is confirmed, the date on which it has been approved for accounting or tax purposes

transaction
string

ID of the transaction.

invoice
string

ID of the invoice.

credit_note
string

ID of the credit note.

tax_evidence
string

ID of the tax_evidence.

product_type
string

Values can be: eservice, standard or ebook.

sale_mode
string

Depending on your client if it is a consumer or a business.

discountable
boolean

Is it discountable or not?

description
string

-

unit_extratax_amount
integer

The unit price of the item without tax.

currency
string

3-letter ISO code for currency.

quantity
integer

A positive integer representing the number of instances of the item.

extratax_amount
integer

The unit price multiplied by the quantity.

tax_rate
float

Tax rate applied to the item.

tax_amount
integer

The tax amount based on the tax rate and the extratax amount.

gross_amount
integer

The amount all tax included.

declare_in_region
string

The country in which the tax is declared.

tax
string

The tax name applied.

item_exchange
hash

The tax currency exchange rate information if relevant.

sources
array

References to the integration’s objects this item has been created from.

item_workspace_currency_exchange
hash

The default workspace currency exchange information if relevant.

Create an item

# Definition
POST https://apiv2.octobat.com/transactions/{TRANSACTION_ID}/items
POST https://apiv2.octobat.com/invoices/{INVOICE_ID}/items
POST https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}/items
# Example Request
$ curl https://apiv2.octobat.com/invoices/oc_in_14619363114yke51e2ce5f/items \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d tax_evidence="oc_tev_1460565379am3be8f5ef71" \
   -d quantity=1 \
   -d currency="USD" \
   -d unit_extratax_amount=19900 \
   -d description="Entreprise Plan"

# Example response
{
  "id": "oc_it_1460568443g3wu6b48fc3e",
  "object": "item",
  "status"=>"draft",
  "confirmed_on": nil,
  "transaction": nil,
  "invoice": "oc_in_14619363114yke51e2ce5f",
  "credit_note": nil,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type"=>"eservice",
  "sale_mode"=>"B2C",
  "discountable"=>true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 19900,
  "currency": "USD",
  "quantity": 1,
  "extratax_amount": 19900,
  "tax_rate": 22.0,
  "tax_amount": 4378,
  "gross_amount": 24278,
  "declare_in_region"=>"IT",
  "tax"=>"VAT",
  "sources": [],
  "item_exchange": {
    "exchange_rate": 0.8864,
    "exchange_date": "2016-04-13T17:27:24.228Z",
    "exchanged_to_currency": "EUR"
  },
  "item_workspace_currency_exchange": {
    "exchange_rate": 0.9526,
    "exchange_date": "2016-04-11T17:27:24.228Z",
    "exchanged_to_currency": "GBP"
  }
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_14619363114yke51e2ce5f")
invoice.items.create(
  tax_evidence: "oc_tev_1460565379am3be8f5ef71",
  quantity: 1,
  currency: "USD",
  unit_extratax_amount: 19900,
  description: "Entreprise Plan"
)

# Example response
#<Octobat::Item id=oc_it_1460568443g3wu6b48fc3e 0x00000a> JSON: {
  "id": "oc_it_1460568443g3wu6b48fc3e",
  "object": "item",
  "status"=>"draft",
  "confirmed_on": nil,
  "transaction": nil,
  "invoice": "oc_in_14619363114yke51e2ce5f",
  "credit_note": nil,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type":"eservice",
  "sale_mode":"B2C",
  "discountable":true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 19900,
  "currency": "USD",
  "quantity": 1,
  "extratax_amount": 19900,
  "tax_rate": 22.0,
  "tax_amount": 4378,
  "gross_amount": 24278,
  "declare_in_region"=>"IT",
  "tax":"VAT",
  "sources": [],
  "item_exchange": {
    "exchange_rate": 0.8864,
    "exchange_date": "2016-04-13T17:27:24.228Z",
    "exchanged_to_currency": "EUR"
  },
  "item_workspace_currency_exchange": {
    "exchange_rate": 0.9526,
    "exchange_date": "2016-04-11T17:27:24.228Z",
    "exchanged_to_currency": "GBP"
  }
}

Arguments

unit_extratax_amount
required

The unit price of the item without tax. Tax-included amount will be computed then. You can choose either to fill `unit_extratax_amount` or `unit_gross_amount` to fix the item price, but filling both will return an error

unit_gross_amount
required

The unit price of the item with tax included. Extratax amount will be computed then. You can choose either to fill `unit_extratax_amount` or `unit_gross_amount` to fix the item price, but filling both will return an error

currency
required

3-letter ISO code for currency.

tax_evidence
optional, either tax_evidence or tax_rate is required

The ID of an existing tax evidence. This is where customer and supplier transaction evidences are stored. The tax rate applied to the item is automatically calculated thanks to the evidences.

tax_rate
optional, either tax_rate or tax_evidence is required

The tax rate that you want apply to the item.

product_type
optional, default is in the “tax settings” section. If the tax_evidence argument is filled, it will have priority.

The product type is either eservice, ebook or standard.

quantity
optional, default is 1

A positive integer representing the number of instances of the item.

description
optional

Item’s description.

Returns

Returns the item object if the creation succeeds. Returns an error if parameters are invalid.

Retrieve an item

# Definition
GET https://apiv2.octobat.com/invoices/{INVOICE_ID}/items/{ITEM_ID}/
GET https://apiv2.octobat.com/transactions/{TRANSACTION_ID}/items/{ITEM_ID}/
GET https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}/items/{ITEM_ID}/

# Example Request
$ curl https://apiv2.octobat.com/invoices/oc_in_14619363114yke51e2ce5f/items/oc_it_1461938887kzsf607ad4cf \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "id": "oc_it_1460568443g3wu6b48fc3e",
  "object": "item",
  "status"=>"draft",
  "confirmed_on": null,
  "transaction": null,
  "invoice": "oc_in_14619363114yke51e2ce5f",
  "credit_note": null,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type"=>"eservice",
  "sale_mode"=>"B2C",
  "discountable"=>true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 19900,
  "currency": "USD",
  "quantity": 1,
  "extratax_amount": 19900,
  "tax_rate": 22.0,
  "tax_amount": 4378,
  "gross_amount": 24278,
  "declare_in_region"=>"IT",
  "tax"=>"VAT",
  "sources": [],
  "item_exchange": {
    "exchange_rate": 0.8864,
    "exchange_date": "2016-04-13T17:27:24.228Z",
    "exchanged_to_currency": "EUR"
  },
  "item_workspace_currency_exchange": {
    "exchange_rate": 0.9526,
    "exchange_date": "2016-04-11T17:27:24.228Z",
    "exchanged_to_currency": "GBP"
  }
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.items.retrieve({ITEM_ID})
# or
transaction = Octobat::Transaction.retrieve({TRANSACTION_ID})
transaction.items.retrieve({ITEM_ID})
# or
credit_note = Octobat::CreditNote.retrieve({CREDIT_NOTE_ID})
credit_note.items.retrieve({ITEM_ID})

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_14619363114yke51e2ce5f")
invoice.items.retrieve("oc_it_1461938887kzsf607ad4cf")

# Example response
#<Octobat::Item id=oc_it_1460568443g3wu6b48fc3e 0x00000a> JSON: {
  "id": "oc_it_1460568443g3wu6b48fc3e",
  "object": "item",
  "status"=>"draft",
  "confirmed_on": nil,
  "transaction": nil,
  "invoice": "oc_in_14619363114yke51e2ce5f",
  "credit_note": nil,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type"=>"eservice",
  "sale_mode"=>"B2C",
  "discountable":true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 19900,
  "currency": "USD",
  "quantity": 1,
  "extratax_amount": 19900,
  "tax_rate": 22.0,
  "tax_amount": 4378,
  "gross_amount": 24278,
  "declare_in_region"=>"IT",
  "tax"=>"VAT",
  "sources": [],
  "item_exchange": {
    "exchange_rate": 0.8864,
    "exchange_date": "2016-04-13T17:27:24.228Z",
    "exchanged_to_currency": "EUR"
  },
  "item_workspace_currency_exchange": {
    "exchange_rate": 0.9526,
    "exchange_date": "2016-04-11T17:27:24.228Z",
    "exchanged_to_currency": "GBP"
  }
}

Retrieves the details of an existing item.

Returns

Returns an item object if a valid identifier was provided.

Update an item

# Definition
PATCH https://apiv2.octobat.com/transactions/{TRANSACTION_ID}/items/{ITEM_ID}
PATCH https://apiv2.octobat.com/invoices/{INVOICE_ID}/items/{ITEM_ID}
PATCH https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}/items/{ITEM_ID}

# Example request
$ curl https://apiv2.octobat.com/invoices/oc_in_1462181488gsc8cf8fafbd/items/oc_it_14621841535d5d3284b1a2 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d quantity=5 \
   -d unit_extratax_amount=1000 \

# Example response
{
  "id": "oc_it_14621841535d5d3284b1a2",
  "object": "item",
  "status"=>"draft",
  "confirmed_on": null,
  "transaction": null,
  "invoice": "oc_in_1462181488gsc8cf8fafbd",
  "credit_note": null,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type"=>"eservice",
  "sale_mode"=>"B2C",
  "discountable"=>true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 1000,
  "currency": "EUR",
  "quantity": 5,
  "extratax_amount": 5000,
  "tax_rate": 22.0,
  "tax_amount": 1100,
  "gross_amount": 6100,
  "declare_in_region"=>"IT",
  "tax"=>"VAT",
  "sources": [],
  "item_exchange": null,
  "item_workspace_currency_exchange": null
}
# Definition
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.items.retrieve({ITEM_ID})
# or
transaction = Octobat::Transaction.retrieve({TRANSACTION_ID})
transaction.items.retrieve({ITEM_ID})
# or
credit_note = Octobat::CreditNote.retrieve({CREDIT_NOTE_ID})
credit_note.items.retrieve({ITEM_ID})

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

invoice = Octobat::Invoice.retrieve("oc_in_1462181488gsc8cf8fafbd")
item = invoice.items.retrieve("oc_it_14621841535d5d3284b1a2")
item.quantity = 5
item.unit_extratax_amount = 1000
item.save


# Example response
#<Octobat::Item id=oc_it_1460568443g3wu6b48fc3e 0x00000a> JSON: {
  "id": "oc_it_14621841535d5d3284b1a2",
  "object": "item",
  "status":"draft",
  "confirmed_on": nil,
  "transaction": nil,
  "invoice": "oc_in_1462181488gsc8cf8fafbd",
  "credit_note": nil,
  "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
  "product_type":"eservice",
  "sale_mode":"B2C",
  "discountable":true,
  "description": "Entreprise Plan",
  "unit_extratax_amount": 1000,
  "currency": "EUR",
  "quantity": 5,
  "extratax_amount": 5000,
  "tax_rate": 22.0,
  "tax_amount": 1100,
  "gross_amount": 6100,
  "declare_in_region":"IT",
  "tax":"VAT",
  "sources": [],
  "item_exchange": null,
  "item_workspace_currency_exchange": null
}

Updates the specified item by setting the values of the parameters passed. Any parameters not provided will be left unchanged. This request accepts mostly the same arguments as the item creation call.

Arguments

unit_extratax_amount
optional

The unit price of the item without tax.

currency
optional

3-letter ISO code for currency.

quantity
optional, default is 1

A positive integer representing the number of instances of the item.

description
optional

Item’s description.

Returns

Returns the item object if the update succeeded. Returns an error if update parameters are invalid.

List all items

# Definition
GET https://apiv2.octobat.com/transactions/{TRANSACTION_ID}/items/
GET https://apiv2.octobat.com/invoices/{INVOICE_ID}/items/
GET https://apiv2.octobat.com/credit_notes/{CREDIT_NOTE_ID}/items/

# Example request
$ curl https://apiv2.octobat.com/transactions/oc_txn_1459936947icq9005f4668/items \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_it_1460568443g3wu6b48fc3e",
      "object": "item",
      "status": "draft",
      "confirmed_on": null,
      "transaction": "oc_txn_14605672518yko2fd30d23",
      "invoice": null,
      "credit_note": null,
      "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
      "product_type": "eservice",
      "sale_mode": "B2C",
      "discountable":true,
      "description": "Entreprise Plan",
      "unit_extratax_amount": 19900,
      "currency": "USD",
      "quantity": 1,
      "extratax_amount": 19900,
      "tax_rate": 22.0,
      "tax_amount": 4378,
      "gross_amount": 24278,
      "declare_in_region": "IT",
      "tax": "VAT",
      "sources": [],
      "item_exchange": {
        "exchange_rate": 0.8864,
        "exchange_date": "2016-04-13T17:27:24.228Z",
        "exchanged_to_currency": "EUR"
      },
      "item_workspace_currency_exchange": {
        "exchange_rate": 0.9526,
        "exchange_date": "2016-04-11T17:27:24.228Z",
        "exchanged_to_currency": "GBP"
      }
    },
    {...},
    {...}
  ]
}
# Definition
transaction = Octobat::Transaction.retrieve({TRANSACTION_ID})
transaction.items.all
# or
invoice = Octobat::Invoice.retrieve({INVOICE_ID})
invoice.items.all
# or
credit_note = Octobat::CreditNote.retrieve({CREDIT_NOTE_ID})
credit_note.items.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

transaction = Octobat::Transaction.retrieve("oc_txn_14605672518yko2fd30d23")
transaction.items.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::Item id=oc_it_1460568443g3wu6b48fc3e 0x00000a> JSON: {
      "id": "oc_it_1460568443g3wu6b48fc3e",
      "object": "item",
      "status": "draft",
      "confirmed_on": nil,
      "transaction": "oc_txn_14605672518yko2fd30d23",
      "invoice": nil,
      "credit_note": nil,
      "tax_evidence": "oc_tev_1460565379am3be8f5ef71",
      "product_type": "eservice",
      "sale_mode": "B2C",
      "discountable":true,
      "description": "Entreprise Plan",
      "unit_extratax_amount": 19900,
      "currency": "USD",
      "quantity": 1,
      "extratax_amount": 19900,
      "tax_rate": 22.0,
      "tax_amount": 4378,
      "gross_amount": 24278,
      "declare_in_region": "IT",
      "tax": "VAT",
      "sources": [],
      "item_exchange": {
        "exchange_rate": 0.8864,
        "exchange_date": "2016-04-13T17:27:24.228Z",
        "exchanged_to_currency": "EUR"
      },
      "item_workspace_currency_exchange": {
        "exchange_rate": 0.9526,
        "exchange_date": "2016-04-11T17:27:24.228Z",
        "exchanged_to_currency": "GBP"
      }
    },
    #<Octobat::Item[...] ...>,
    #<Octobat::Item[...] ...>
  ]
}

Returns a list of items.

Returns

A hash with a data property that contains an array of items. Each entry in the array is a separate item object. If no items are available, the resulting array will be empty. This request should never raise an error.

Transactions

This is a transaction. It triggers when there is a payment or a refund.

The transaction object

Example object

{
  "id": "oc_txn_1459936947icq9005f4668",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": null,
  "credit_note": null,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}
{
  "id": "oc_txn_1459936947icq9005f4668",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": nil,
  "credit_note": nil,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}

Attributes

id
string

-

object
string, value is “transaction

-

customer
string

ID of the customer.

payment_source
string

ID of the payment source.

payment_recipient
string

ID of the payment recipient.

invoice
string

ID of the invoice if one exists.

credit_note
string

ID of the credit note if one exists.

livemode
boolean

-

status
string

The status of the transaction is either succeeded, pending, or failed.

transaction_date
string

Date on which the transaction was created.

flow_type
string

The type of the transaction is either payment or refund.

amount
integer

The total amount that the customer has paid.

sources
array

References to the integration’s objects this transaction has been created from.

currency
string

Three-letter ISO code representing the currency of the transaction.

Create a transaction

# Definition
POST https://apiv2.octobat.com/transactions
# Example Request
$ curl https://apiv2.octobat.com/transactions \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d customer="oc_cu_1459413729au6o6a9ae061" \
   -d payment_source="oc_ps_1459584112d83k4ef3e3bd" \
   -d payment_recipient="oc_pr_14597887132yzs440d46e9" \
   -d invoice="oc_in_14597887132yzs440der49" \
   -d status="succeeded" \
   -d flow_type="payment" \
   -d amount=2500 \
   -d currency="EUR"

# Example response
{
  "id": "oc_txn_1459936947icq9005f4668",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": "oc_in_14597887132yzs440der49",
  "credit_note": nil,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Transaction.create(
  customer: "oc_cu_1459413729au6o6a9ae061",
  payment_source: "oc_ps_1459584112d83k4ef3e3bd",
  payment_recipient: "oc_pr_14597887132yzs440d46e9",
  invoice: "oc_in_14597887132yzs440der49",
  status: "succeeded",
  flow_type: "payment",
  amount: 2500,
  currency: 'EUR'
)

# Example response
#<Octobat::Transaction id=oc_txn_1459936947icq9005f4668 0x00000a> JSON: {
  "id": "oc_txn_1459936947icq9005f4668",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": "oc_in_14597887132yzs440der49",
  "credit_note": nil,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}

Arguments

customer
required

The ID of an existing customer that will be charged in this request.

payment_source
optional, default is nil

The ID of an existing payment source.

payment_recipient
required

The ID of an existing payment recipient.

invoice
optional, default is nil

The ID of an existing invoice.

credit_note
optional, default is nil

The ID of an existing credit note.

status
required

The status of the transaction is either succeeded or failed.

transaction_date
optional, default is current datetime

Date on which the transaction was created.

flow_type
required

The type of the transaction is either payment or refund.

amount
required

The total amount that the customer has paid.

currency
required

Three-letter ISO code representing the currency of the transaction.

Returns

Returns the transaction object if the creation succeeds. Returns an error if parameters are invalid

Retrieve a transaction

# Definition
GET https://apiv2.octobat.com/transactions/{TRANSACTION_ID}

# Example Request
$ curl https://apiv2.octobat.com/transactions/oc_txn_1459957855kw89e9c7e960 \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "id": "oc_txn_1459957855kw89e9c7e960",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": "oc_in_14597887132yzs440der49",
  "credit_note": nil,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}
# Definition
Octobat::Transaction.retrieve({TRANSACTION_ID})

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Transaction.retrieve("oc_txn_1459957855kw89e9c7e960")

# Example response
#<Octobat::Transaction id=oc_txn_1459957855kw89e9c7e960 0x00000a> JSON: {
  "id": "oc_txn_1459957855kw89e9c7e960",
  "object": "transaction",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
  "payment_recipient": "oc_pr_14597887132yzs440d46e9",
  "invoice": "oc_in_14597887132yzs440der49",
  "credit_note": nil,
  "livemode": true,
  "status": "succeeded",
  "transaction_date": "2016-03-31T00:00:00.000Z",
  "flow_type": "payment",
  "amount": 2500,
  "currency": "EUR",
  "sources": []
}

Retrieves the details of an existing transaction.

Arguments

transaction
required

The identifier of the transaction to be retrieved.

Returns

Returns a transaction object if a valid identifier was provided.

List all transactions

# Definition
GET https://apiv2.octobat.com/transactions/

# Example request
$ curl https://apiv2.octobat.com/transactions \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_txn_1459957855kw89e9c7e960",
      "object": "transaction",
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
      "payment_recipient": "oc_pr_14597887132yzs440d46e9",
      "invoice": "oc_in_14597887132yzs440der49",
      "credit_note": nil,
      "livemode": true,
      "status": "succeeded",
      "transaction_date": "2016-03-31T00:00:00.000Z",
      "flow_type": "payment",
      "amount": 1500,
      "currency": "EUR",
      "sources": []
    },
    {...},
    {...}
  ]
}
# Definition
Octobat::Transaction.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::Transaction.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::Transaction id=oc_txn_1459957855kw89e9c7e960 0x00000a> JSON: {
      "id": "oc_txn_1459957855kw89e9c7e960",
      "object": "transaction",
      "customer": "oc_cu_1459413729au6o6a9ae061",
      "payment_source": "oc_ps_1459584112d83k4ef3e3bd",
      "payment_recipient": "oc_pr_14597887132yzs440d46e9",
      "invoice": "oc_in_14597887132yzs440der49",
      "credit_note": nil,
      "livemode": true,
      "status": "succeeded",
      "transaction_date": "2016-03-31T00:00:00.000Z",
      "flow_type": "payment",
      "amount": 1500,
      "currency": "EUR",
      "sources": []
    },
    #<Octobat::Transaction[...] ...>,
    #<Octobat::Transaction[...] ...>
  ]
}

Returns a list of transactions.

Returns

A hash with a data property that contains an array of transactions. Each entry in the array is a separate transaction object. If no transactions are available, the resulting array will be empty. This request should never raise an error.

Payment recipients

The payment recipient object

Example object

{
  "id": "oc_pr_14597887132yzs440d46e9",
  "object": "payment_recipient",
  "livemode": true,
  "name": "Transfer",
  "details": {
    "iban": "FR90 17216 18009 17038133245 88"
  }
}

Attributes

id
string

-

object
string, value is “payment_recipient

-

livemode
boolean

-

name
string

Name or description of the payment recipient.

details
json

Details addressed to the customer, to recieve the payment (IBAN, check recipient…).

Listing payment recipients

# Definition
GET https://apiv2.octobat.com/payment_recipients/

# Example request
$ curl https://apiv2.octobat.com/payment_recipients \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_pr_14597887132yzs440d46e9",
      "object": "payment_recipient",
      "livemode": true,
      "name": "Transfer",
      "details": {
        "iban": "FR90 17216 18009 17038133245 88"
      }
    },
    {...},
    {...}
  ]
}
# Definition
Octobat::PaymentRecipient.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::PaymentRecipient.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::PaymentRecipient id=oc_pr_14597887132yzs440d46e9 0x00000a> JSON: {
      "id": "oc_pr_14597887132yzs440d46e9",
      "object": "payment_recipient",
      "livemode": true,
      "name": "Transfer",
      "details": {
        "iban": "FR90 17216 18009 17038133245 88"
      }
    },
    #<Octobat::PaymentRecipient[...] ...>,
    #<Octobat::PaymentRecipient[...] ...>
  ]
}

Returns a list of payment recipients.

Returns

A hash with a data property that contains an array of payment recipients. Each entry in the array is a separate numbering payment recipient. If no payment recipients are available, the resulting array will be empty. This request should never raise an error.

Payment sources

This is the payment source of a transaction.

The payment source object

Example object

{
  "id": "oc_ps_1459584112d83k4ef3e3bd",
  "object": "payment_source",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "source": "card_1029383qsfqs",
  "payment_source_type": "Credit Card",
  "details": {},
  "country": "FR",
  "exp_month": 12,
  "exp_year": 2017
}

Attributes

id
string

-

object
string, value is “payment_source

-

customer
string

ID of the customer.

source
string

Source.

payment_source_type
string

Type of the payment can be Credit Card, Transfer, or Check or another value.

details
json

-

country
string

Two-letter ISO code representing the country of the payment source.

exp_month
integer

-

exp_year
integer

-

Create a payment source

# Definition
POST https://apiv2.octobat.com/customers/{CUSTOMER_ID}/payment_sources
# Example Request
$ curl https://apiv2.octobat.com/customers/{CUSTOMER_ID}/payment_sources \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt: \
   -d source="card_1029383qsfqs" \
   -d payment_source_type="Credit Card" \
   -d details={} \
   -d country="FR" \
   -d exp_month=12 \
   -d exp_year=2017

# Example response
{
  "id": "oc_ps_1459584112d83k4ef3e3bd",
  "object": "payment_source",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "source": "card_1029383qsfqs",
  "payment_source_type": "Credit Card",
  "details": {},
  "country": "FR",
  "exp_month": 12,
  "exp_year": 2017
}
# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

customer = Octobat::Customer.retrieve("oc_cu_1459413729au6o6a9ae061")
customer.payment_sources.create(
  source: "card_1029383qsfqs",
  payment_source_type: "Credit Card",
  details: {},
  country: "FR",
  exp_month: 12,
  exp_year: 2017
)

# Example response
#<Octobat::PaymentSource id=oc_ps_1459584112d83k4ef3e3bd 0x00000a> JSON: {
  "id": "oc_ps_1459584112d83k4ef3e3bd",
  "object": "payment_source",
  "customer": "oc_cu_1459413729au6o6a9ae061",
  "source": "card_1029383qsfqs",
  "payment_source_type": "Credit Card",
  "details": {},
  "country": "FR",
  "exp_month": 12,
  "exp_year": 2017
}

Arguments

source
optional

-

payment_source_type
optional

-

details
optional

-

country
optional

Two-letter ISO code representing the payment source’s country of the customer.

exp_month
optional, default is nil

-

exp_year
optional, default is nil

-

Returns

Returns the payment source object if the creation succeeds. Returns an error if parameters are invalid

Retrieve an existing payment source

# Definition
GET https://apiv2.octobat.com/customers/{CUSTOMER_ID}/payment_sources/{PAYMENT_SOURCE_ID}

# Example Request
$ curl https://apiv2.octobat.com/customers/oc_cu_1421878635hksc26e4de79/payment_sources/oc_ps_1459584051gau52bfe848c \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "id": "oc_ps_1459584051gau52bfe848c",
  "object" : "payment_source",
  "customer" : "oc_cu_1459413729au6o6a9ae061",
  "source": "card_1029383qsfqs",
  "payment_source_type": "Credit Card",
  "details": {},
  "country": FR,
  "exp_month": 12,
  "exp_year": 2017
}
# Definition
customer = Octobat::Customer.retrieve({CUSTOMER_ID})
payment_source = customer.payment_sources.retrieve({PAYMENT_SOURCE_ID})

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

customer = Octobat::Customer.retrieve("oc_cu_1421878635hksc26e4de79")
customer.payment_sources.retrieve("oc_ps_1459584112d83k4ef3e3bd")

# Example response
#<Octobat::PaymentSource id=oc_ps_1459584112d83k4ef3e3bd 0x00000a> JSON: {
 "id": "oc_ps_1459584112d83k4ef3e3bd",
 "object" : "payment_source",
 "customer" : "oc_cu_1459413729au6o6a9ae061",
 "source": "card_1029383qsfqs",
 "payment_source_type": "Credit Card",
 "details": {},
 "country": FR,
 "exp_month": 12,
 "exp_year": 2017
}

Retrieves the details of an existing payment source. You need only supply the unique payment source identifier that was returned upon payment source creation.

Arguments

id
required

The identifier of the payment source to be retrieved.

Returns

Returns a payment source object if a valid identifier was provided.

List all payment sources

# Definition
GET https://apiv2.octobat.com/customers/{CUSTOMER_ID}/payment_sources/

# Example request
$ curl https://apiv2.octobat.com/customers/oc_cu_1459413729au6o6a9ae061/payment_sources \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_ps_1459584112d83k4ef3e3bd",
      "object" : "payment_source",
      "customer" : "oc_cu_1459413729au6o6a9ae061",
      "source": "card_1029383qsfqs",
      "payment_source_type": "Credit Card",
      "details": {},
      "country": "FR",
      "exp_month": 12,
      "exp_year": 2017
    },
    {...},
    {...}
  ]
}
# Definition
customer = Octobat::Customer.retrieve({CUSTOMER_ID})
customer.payment_sources.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

customer = Octobat::Customer.retrieve("oc_cu_1459413729au6o6a9ae061")
customer.payment_sources.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::PaymentSource id=oc_ps_1459584112d83k4ef3e3bd 0x00000a> JSON: {
      "id": "oc_ps_1459584112d83k4ef3e3bd",
      "object" : "payment_source",
      "customer" : "oc_cu_1459413729au6o6a9ae061",
      "source": "card_1029383qsfqs",
      "payment_source_type": "Credit Card",
      "details": {},
      "country": "FR",
      "exp_month": 12,
      "exp_year": 2017
    },
    #<Octobat::PaymentSource[...] ...>,
    #<Octobat::PaymentSource[...] ...>
  ]
}

Returns a list of customer’s payment sources.

Returns

A hash with a data property that contains an array of payment sources. Each entry in the array is a separate payment source object. If no payment sources are available, the resulting array will be empty. This request should never raise an error.

Invoice Numbering sequences

The invoice numbering sequence object

Example object

{
  "id": "oc_ns_146192091741t5175c8c47",
  "object": "invoice_numbering_sequence",
  "prefix": "AAA-",
  "is_default": true,
  "next_number": "AAA-1"
}

Attributes

id
string

-

object
string, value is “invoice_numbering_sequence

-

prefix
string

The prefix of each invoice number in this sequence.

is_default
string

Only one numbering sequence can be the default one, which is selected if no numbering sequence is chosen during invoice creation.

next_number
string

The next invoice number that will be generated within this sequence.

Listing invoice numbering sequences

# Definition
GET https://apiv2.octobat.com/invoice_numbering_sequences/

# Example request
$ curl https://apiv2.octobat.com/invoice_numbering_sequences \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_ns_146192091741t5175c8c47",
      "object": "invoice_numbering_sequence",
      "prefix": "AAA-",
      "is_default": true,
      "next_number": "AAA-1"
    },
    {...},
    {...}
  ]
}
# Definition
Octobat::InvoiceNumberingSequence.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::InvoiceNumberingSequence.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::InvoiceNumberingSequence id=oc_ns_146192091741t5175c8c47 0x00000a> JSON: {
      "id": "oc_ns_146192091741t5175c8c47",
      "object": "invoice_numbering_sequence",
      "prefix": "AAA-",
      "is_default": true,
      "next_number": "AAA-1"
    },
    #<Octobat::InvoiceNumberingSequence[...] ...>,
    #<Octobat::InvoiceNumberingSequence[...] ...>
  ]
}

Returns a list of invoice numbering sequences.

Returns

A hash with a data property that contains an array of invoice numbering sequences. Each entry in the array is a separate numbering sequence object. If no numbering sequence are available, the resulting array will be empty. This request should never raise an error.

Credit note Numbering sequences

The credit note numbering sequence object

Example object

{
  "id": "oc_cns_1462279395ko79c927206e",
  "object": "credit_note_numbering_sequence",
  "prefix": "CN-AAA-",
  "is_default": true,
  "next_number": "CN-AAA-1"
}

Attributes

id
string

-

object
string, value is “credit_note_numbering_sequence

-

prefix
string

The prefix of each credit note number in this sequence.

is_default
string

Only one numbering sequence can be the default one, which is selected if no numbering sequence is chosen during credit note creation.

next_number
string

The next credit note number that will be generated within this sequence.

Listing credit note numbering sequences

# Definition
GET https://apiv2.octobat.com/credit_note_numbering_sequences/

# Example request
$ curl https://apiv2.octobat.com/credit_note_numbering_sequences \
   -u oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt:

# Example response
{
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    {
      "id": "oc_cns_14622823144wil0b9768b2",
      "object": "credit_note_numbering_sequence",
      "prefix": "CN-AAA-",
      "is_default": true,
      "next_number": "CN-AAA-1"
    },
    {...},
    {...}
  ]
}
# Definition
Octobat::CreditNoteNumberingSequence.all

# Example request
>> require "octobat"
Octobat.api_key = "oc_test_skey_tkHCYYOUVrYyY5rBFZxNzgtt"

Octobat::CreditNoteNumberingSequence.all

# Example response
#<Octobat::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "has_before": false,
  "has_more": false,
  "total_count": 3,
  "data": [
    #<Octobat::CreditNoteNumberingSequence id=oc_cns_14622823144wil0b9768b2 0x00000a> JSON: {
      "id": "oc_cns_14622823144wil0b9768b2",
      "object": "credit_note_numbering_sequence",
      "prefix": "CN-AAA-",
      "is_default": true,
      "next_number": "CN-AAA-1"
    },
    #<Octobat::CreditNoteNumberingSequence[...] ...>,
    #<Octobat::CreditNoteNumberingSequence[...] ...>
  ]
}

Returns a list of credit note numbering sequences.

Returns

A hash with a data property that contains an array of credit note numbering sequences. Each entry in the array is a separate numbering sequence object. If no numbering sequence are available, the resulting array will be empty. This request should never raise an error.