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 |
| 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 |
| 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 |
| 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 |
| status string |
The status of the invoice is either |
| 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 |
| 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 |
| status string |
The status of the credit note is either |
| 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 |
| product_type optional, default is your product_type setting. |
The product type is either |
| 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: |
| product_type optional |
The product type is either |
| 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: |
| 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 |
| 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 |
| transaction_date string |
Date on which the transaction was created. |
| flow_type string |
The type of the transaction is either |
| 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 |
| transaction_date optional, default is current datetime |
Date on which the transaction was created. |
| flow_type required |
The type of the transaction is either |
| 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 |
| 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.