Introduction

Paid is a simple API to collect and translate your customer transaction data into an automated invoicing solution.

The way it works: simply add our API requests at transaction trigger points in your code. These events will be tracked for each of your customers, and an invoice will be sent on your pre-determined billing cycle. Your customers can easily pay you via Credit Card, ACH, Wire, check and more. We have automatic follow-ups, helping customers to never lose track of transactions.

For more information, or to sign up, follow the links below:

Home Page

Sign Up

Getting Started Guide

Questions? Do not hesitate to reach out: hello@paidlabs.com

Libraries

Paid offers libraries to help developers easily use the API in any language. If your language isn’t supported, let us know. Often, we have a beta version or we can build one for you!

• Ruby
• Node

Authentication

The Paid API is organized around REST. You will need your API key to access all routes.

You authenticate to the Paid API by supplying your API keys in the request. Your API Key gives you full access to the API, so be sure to keep it secret!

We use HTTP Basic Auth for the Paid API. Provide your API key as the basic auth username. Do not need to provide a password. You must authenticate for all requests and may only make requests over HTTPS. Calls made over plain HTTP will fail.

$ curl https://api.paidlabs.com/v0/account \
   -u sk_test_nUbl45Q7BQhioCNVhSw:

require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

We’ve added a test key for you so you can test requests right away. Make sure to replace sk_test_nUbl45Q7BQhioCNVhSw with your API key when building your own application.

Errors

HTTP Status Code Summary

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
403 Forbidden (Rate Limit Exceeded) - You have exceeded the request limit.
404 Not Found - The requested item doesn’t exist.
500, 502, 503, 504 Server errors - something went wrong on Paid’s end.

Paid API uses regular HTTP response codes. Not all errors map cleanly to an HTTP response code. In general, 2xx codes indicate success. 4xx codes indicate an error with supplied parameters. 5xx codes indicate an error with Paid’s servers.

Attributes

Parameter	Description
type	Type of the error returned. Can be invalid_request_error or api_error.
message	A human-readable message letting you know exactly what went wrong.
param	(optional) The parameter the error relates to.

HTTP Status Code Summary

Code	Description
200	OK - Everything worked as expected.
400	Bad Request - Often missing a required parameter.
401	Unauthorized - No valid API key provided.
402	Upgrade Required - You must upgrade your plan to make this request.
404	Not Found - The requested item doesn’t exist.
500, 502, 503, 504	Server errors - something went wrong on Paid’s end.

Pagination

All major objects in Paid support list API methods. Some examples are listing transactions, listing customers, etc. All list responses share a common structure.

Paid supports cursor-based pagination, using the parameter starting_after to change where each page starts. See a full list of pagination parameters below. Note that all pagination parameters must be passed in the pagination hash.

Arguments

Argument	Description
pagination[limit]	optional default is 25
pagination[starting_after]	optional An object ID to use in pagination. For example, you receive a list of objects in a request ending with obj_foo, include pagination[starting_after]=obj_foo to get the next page.
pagination[ending_before]	optional An object ID to use in pagination. For example, you receive a list of objects in a request starting with obj_foo, include pagination[ending_before]=obj_foo to get the previous page.

Dates & Times

Paid uses UTC unix timestamps for all dates and times. Please note that if a field is marked as a date (usually specified as *_on rather than *_at), the time portion will be ignored. For example, if you supply paid_on = 1426021736 representing 2015-03-10 21:08:56 UTC or (Time.at(1426021736).utc), Paid will use only the date portion. Dates will always return the correct date portion and will usually have the time portion set to midnight.

Filter by created_at

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions?created_at[gt]=1437924748 \
--globoff \
-u sk_test_nUbl45Q7BQhioCNVhSw:

{
  "object": "list",
  "data": [
    {
      "id": "tr_3fj38099dalkxie",
      "object": "transaction",
      "amount": 100,
      "currency": "usd",
      "description": "Designing awesome holiday cards.",
      "customer": "cus_83dkEOckd920dE",
      "metadata": {
        "promotion":"holiday_cards",
        "discount":"bulk_100"
      },
      "paid": false,
      "paid_on": null,
      "serviced_on": 1431325733,
      "invoice": null
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Transaction.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Transaction.all({
  created_at: {
    gt: 1437924748
  }
}

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
      "id": "tr_3fj38099dalkxie",
      "object": "transaction",
      "amount": 100,
      "description": "Designing awesome holiday cards.",
      "customer": "cus_83dkEOckd920dE",
      "paid": false,
      "paid_on": null,
      "serviced_on": 1431325733,
      "metadata": {
      },
      "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
    },
    #<Paid::Transaction[...] ...>,
    #<Paid::Transaction[...] ...>
  ]
}

Sample Arguments

Argument	Description
created_at	optional A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp: gt for greater than gte for greater than or equal to lt for less than lte for less thank or equal to

Throttling

The default throttling limit for Paid’s APIs is 100 requests per minute. If you exceed this limit, you will receive a 403 Forbidden (Rate Limit Exceeded) error and should try again once the limit has reset.

—

Account

The account object

Retrieve your account to see properties on the account.

Attributes

Parameter	Description
id	string
object	string value is “account”
business_name	string
business_url	string
business_logo	string URL pointing to business logo

{
  "id": "acct_zuqdGPGi7Q1ZDSWAgjtJg",
  "object": "account",
  "business_name": "[TEST] Developers",
  "business_url": "www.paidlabs.com",
  "business_logo": null
}

#<Paid::Account:0x3fdc22e334cc id=acct_zuqdGPGi7Q1ZDSWAgjtJg> JSON: {
  "object": "account",
  "id": "acct_zuqdGPGi7Q1ZDSWAgjtJg",
  "business_name": "[TEST] Developers",
  "business_url": "www.paidlabs.com",
  "business_logo": ""
}

Retrieve account details

DEFINITION
GET https://api.paidlabs.com/v0/account

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/account \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "acct_nXB9sP3AbaP2SQdnMWCMw",
  "object": "account",
  "business_name": null,
  "business_url": null,
  "business_logo": null
}

DEFINITION
Paid::Account.retrieve()

EXAMPLE REQUEST
require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Account.retrieve()

EXAMPLE RESPONSE
#<Paid::Account:0x3fdc22e334cc id=acct_zuqdGPGi7Q1ZDSWAgjtJg> JSON: {
  "object": "account",
  "id": "acct_zuqdGPGi7Q1ZDSWAgjtJg",
  "business_name": "[TEST] Developers",
  "business_url": "www.paidlabs.com",
  "business_logo": ""
}

Retrieves the account details based on the API key used to authenticate the request.

Arguments

No Arguments

RETURNS

An account object for the API key used to authenticate the request.

Update account

DEFINITION
PUT https://api.paidlabs.com/v0/account

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/account \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d "description=Changing the description." \

EXAMPLE RESPONSE
{
  "id": "acct_nXB9sP3AbaP2SQdnMWCMw",
  "object": "account",
  "address_city": "Paid",
  "address_country": "hello@paidlabs.com",
  "address_line1": "198454",
  "address_line2": "Changing the description.",
  "address_state": "2261 Market Street",
  "address_zip": "#567",
  "business_name": "San Francisco",
  "business_phone": "4155069330",
  "business_support_email": "94114",
  "business_url": "US",
  "tax_id": "4155069330",
  "tax_id_label": true
}

DEFINITION
Paid::Account.retrieve()

EXAMPLE REQUEST
require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

a = Paid::Account.retrieve("acct_zuqdGPGi7Q1ZDSWAgjtJg")
a.business_name = "This is a new name."
a.save

EXAMPLE RESPONSE
#<Paid::Account:0x3fdc22e334cc id=acct_zuqdGPGi7Q1ZDSWAgjtJg> JSON: {
  "object": "account",
  "id": "acct_zuqdGPGi7Q1ZDSWAgjtJg",
  "business_name": "[TEST] Developers",
  "business_url": "www.paidlabs.com",
  "business_logo": ""
}

Updates account by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
business_name	optional The name of your business.
business_phone	optional
business_support_email	optional
business_url	optional
address_line1	optional
address_line2	optional
address_city	optional
address_state	optional
address_zip	optional
address_country	optional
tax_id	optional
tax_id_label	optional

Returns

An account object for the API key used to authenticate the request.

—

Customers

The customer object

{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Attributes

Parameter	Description
id	string
object	string value is “customer”
name	string This name will appear on customer invoices. We recommend using the full legal name of the customer.
description	string
email	string
external_id	string
phone	string
address_line1	string
address_line2	string
address_city	string
address_state	string
address_zip	string
address_country	string Two-letter ISO country code.
allow_ach	boolean
allow_wire	boolean
allow_check	boolean
allow_credit_card	boolean
allow_paypal	boolean
auto_generate	boolean When auth_generate is set to true, every new transaction will result in a new invoice being generated. The transaction will be automatically put on that invoice.
auto_issue	boolean When auth_issue is set to true, when an invoice is created, it will automatically be issued, regardless of the amount.
billing_type	string Value can be 'invoice' or 'charge'. Customers with billing_type='charge' will have their credit card charged immediately when an invoice is issued. We currently support charging through Stripe, so stripe_customer_id must be set in order to enable charging.
billing_cycle	string Value can be 'manual', 'weekly' or 'monthly'.
cc_emails	string A comma separated list of email addresses.
metadata	metadata hash A hash of key/value pairs used for storing additional information about the transaction in a structured format.
notes	string
roll_up_communications	boolean
stripe_customer_id	string
tax_id	string
tax_id_label	string default is ‘Tax ID’
terms	integer

Create a new customer

DEFINITION
POST https://api.paidlabs.com/v0/customers

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d name=Paid \
    -d email=hello@paidlabs.com \
    -d "description=Obviously this is just a description." \
    -d "address_phone=4155069330" \
    -d "address_line1=2261 Market Street" \
    -d "address_line2=#567" \
    -d "address_city=San Francisco" \
    -d "address_state=CA" \
    -d "address_zip=94114" \
    -d "address_country=US"

EXAMPLE RESPONSE
{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

DEFINITION

Paid::Customer.create

EXAMPLE REQUEST
require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Customer.create(
  :name => "Paid",
  :email => "hello@paidlabs.com",
  :description => "Obviously this is just a description.",
  :phone => "4155069330",
  :address_line1 => "2261 Market Street",
  :address_line2 => "#567",
  :address_city => "San Francisco",
  :address_state => "CA",
  :address_zip => "94114",
  :address_country => "US"
)

EXAMPLE RESPONSE
#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Create a customer by making a single call to the API.

Arguments

Argument	Description
name	optional The name of your customer.
email	optional An email address of the main contact for your customer.
description	optional
external_id	optional
phone	optional
address_line1	optional
address_line2	optional
address_city	optional
address_state	optional
address_zip	optional
address_country	optional
allow_ach	optional
allow_wire	optional
allow_check	optional
allow_credit_card	optional
allow_paypal	optional
auto_generate	optional
auto_issue	optional
billing_type	optional
billing_cycle	optional
cc_emails	optional A comma separated list of email addresses.
metadata	optional default is { } A hash of key/value pairs used for storing additional information about the transaction in a structured format.
notes	optional
roll_up_communications	optional
stripe_customer_id	optional
tax_id	optional
tax_id_label	optional
terms	optional

Retrieve an existing customer

DEFINITION
GET https://api.paidlabs.com/v0/customers/{customer_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_DLjf9aDKE9fkdncz \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

DEFINITION
Paid::Customer.retrieve({CUSTOMER_ID})

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Customer.retrieve("cus_DLjf9aDKE9fkdncz")

EXAMPLE RESPONSE
#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Retrieves the details of a customer that has previously been created. Supply a unique customer ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the customer to be retrieved.

Returns

Returns a customer object if a valid identifier was provided, and returns an error otherwise.

Retrieve using external_id

DEFINITION
GET https://api.paidlabs.com/v0/customers/by_external_id?external_id={EXTERNAL_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/by_external_id?external_id=198454 \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

DEFINITION
Paid::Customer.by_external_id({EXTERNAL_ID})

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Customer.by_external_id("198454")

EXAMPLE RESPONSE
#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Obviously this is just a description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Retrieves or creates a customer using the external_id provided.

Arguments

Argument	Description
external_id	required The identifier of the customer to be retrieved.

Returns

This is special route that will create a customer with the passed external_id if one is now found. Returns a customer object if a valid identifier was provided. Otherwise, it creates a new customer with the passed attributes (including external_id).

Update a customer

DEFINITION
PUT https://api.paidlabs.com/v0/customers/{CUSTOMER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_DLjf9aDKE9fkdncz \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d "description=Changing the description." \

EXAMPLE RESPONSE
{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Changing the description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

DEFINITION
c = Paid::Customer.retrieve({CUSTOMER_ID})
c.description = {NEW_DESCRIPTION}
...
c.save

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

c = Paid::Customer.retrieve("cus_DLjf9aDKE9fkdncz")
c.description = "This is a new description."
c.save

EXAMPLE RESPONSE
#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "This is a new description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
name	optional The name of your customer.
email	optional An email address of the main contact for your customer.
description	optional
external_id	optional
phone	optional
address_line1	optional
address_line2	optional
address_city	optional
address_state	optional
address_zip	optional
address_country	optional
allow_ach	optional
allow_wire	optional
allow_check	optional
allow_credit_card	optional
allow_paypal	optional
auto_generate	optional
auto_issue	optional
billing_type	optional
billing_cycle	optional
cc_emails	optional A comma separated list of email addresses.
metadata	optional default is { } A hash of key/value pairs used for storing additional information about the transaction in a structured format.
notes	optional
roll_up_communications	optional
stripe_customer_id	optional
tax_id	optional
tax_id_label	optional
terms	optional

Update using external_id

DEFINITION
POST https://api.paidlabs.com/v0/customers/by_external_id?external_id={EXTERNAL_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/by_external_id?external_id=198454 \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d "description=Changing the description." \
    -X POST

EXAMPLE RESPONSE
{
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "Changing the description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

DEFINITION
c = Paid::Customer.by_external_id({EXTERNAL_ID})
c.description = {NEW_DESCRIPTION}
...
c.save

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

c = Paid::Customer.by_external_id("198454")
c.description = "This is a new description."
c.save

EXAMPLE RESPONSE
#<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
  "id": "cus_DLjf9aDKE9fkdncz",
  "object": "customer",
  "name": "Paid",
  "email": "hello@paidlabs.com",
  "external_id": "198454",
  "description": "This is a new description.",
  "address_line1": "2261 Market Street",
  "address_line2": "#567",
  "address_city": "San Francisco",
  "address_state": "CA",
  "address_zip": "94114",
  "address_country": "US",
  "phone": "4155069330",
  "allow_ach": true,
  "allow_check": true,
  "allow_credit_card": true,
  "allow_wire": true,
  "terms": 30,
  "billing_type": "invoice",
  "billing_cycle": "manual",
  "metadata": {

  },
  "stripe_customer_id": null,
  "tax_id": null,
  "tax_id_label": "Tax ID"
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
name	optional The name of your customer.
email	optional An email address of the main contact for your customer.
description	optional
external_id	optional
phone	optional
address_line1	optional
address_line2	optional
address_city	optional
address_state	optional
address_zip	optional
address_country	optional
allow_ach	optional
allow_wire	optional
allow_check	optional
allow_credit_card	optional
allow_paypal	optional
auto_generate	optional
auto_issue	optional
billing_type	optional
billing_cycle	optional
cc_emails	optional A comma separated list of email addresses.
notes	optional
roll_up_communications	optional
stripe_customer_id	optional
tax_id	optional
tax_id_label	optional
terms	optional

List all customers

DEFINITION
GET https://api.paidlabs.com/v0/customers

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "cus_DLjf9aDKE9fkdncz",
      "object": "customer",
      "name": "Paid",
      "email": "hello@paidlabs.com",
      "external_id": "198454",
      "description": "Obviously this is just a description.",
      "address_line1": "2261 Market Street",
      "address_line2": "#567",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94114",
      "address_country": "US",
      "phone": "4155069330",
      "allow_ach": true,
      "allow_check": true,
      "allow_credit_card": true,
      "allow_wire": true,
      "terms": 30,
      "billing_type": "invoice",
      "billing_cycle": "manual",
      "metadata": {

      },
      "stripe_customer_id": null,
      "tax_id": null,
      "tax_id_label": "Tax ID"
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Customer.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Customer.all

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Customer id=cus_DLjf9aDKE9fkdncz 0x00000a> JSON: {
      "id": "cus_DLjf9aDKE9fkdncz",
      "object": "customer",
      "name": "Paid",
      "email": "hello@paidlabs.com",
      "external_id": "198454",
      "description": "This is a new description.",
      "address_line1": "2261 Market Street",
      "address_line2": "#567",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94114",
      "address_country": "US",
      "phone": "4155069330",
      "allow_ach": true,
      "allow_check": true,
      "allow_credit_card": true,
      "allow_wire": true,
      "terms": 30,
      "billing_type": "invoice",
      "billing_cycle": "manual",
      "metadata": {

      },
      "stripe_customer_id": null,
      "tax_id": null,
      "tax_id_label": "Tax ID"
    },
    #<Paid::Customer[...] ...>,
    #<Paid::Customer[...] ...>,
  ]
}

Returns a list of all customers you’ve previously created. The customers are returned in sorted order, with the most recent customers appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

Generate invoices for customer

DEFINITION
POST https://api.paidlabs.com/v0/customers/{CUSTOMER_ID}/generate_invoices

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_DLjf9aDKE9fkdncz/generate_invoices \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "cus_DLjf9aDKE9fkdncz",
      "object": "customer",
      "name": "Paid",
      "email": "hello@paidlabs.com",
      "external_id": "198454",
      "description": "Obviously this is just a description.",
      "address_line1": "2261 Market Street",
      "address_line2": "#567",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94114",
      "address_country": "US",
      "phone": "4155069330",
      "allow_ach": true,
      "allow_check": true,
      "allow_credit_card": true,
      "allow_wire": true,
      "terms": 30,
      "billing_type": "invoice",
      "billing_cycle": "manual",
      "metadata": {

      },
      "stripe_customer_id": null,
      "tax_id": null,
      "tax_id_label": "Tax ID"
    },
    { ... },
    { ... },
  ]
}

Generate all invoices for a customer that have not been previously.

Arguments

See Pagination section for supported pagination arguments.

Transactions

The transaction object

{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Designing awesome holiday cards.",
  "customer": "cus_83dkEOckd920dE",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

EXAMPLE OBJECT
#<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Designing awesome holiday cards.",
  "customer": "cus_83dkEOckd920dE",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Attributes

Parameter	Description
id	string
object	string value is “transaction”
amount	integer Amount is in cents
description	string
customer	string
currency	string
customer_external_id	string If a customer with the external_id exists, it will be used for this transaction. Otherwise, Paid will automatically create a new customer with its external_id set to this value. External ID is particularly useful when getting started—simply use your own systems unique IDs for your customers.
rank	integer
paid	boolean
paid_at	string
serviced_on	date The date displayed on the invoice.
service_starts_on	date
service_ends_on	date
status	string
metadata	metadata hash A hash of key/value pairs used for storing additional information about the transaction in a structured format.
invoice	string ID of invoice if one is assigned
group_by	string This string is used when generating invoices. Only transactions with the same group_by will be placed on the same invoice. For example, if you create two transactions one with group_by = 'asdf' and the other with group_by = '1234', calling generate_invoices will return a list of two invoices (assuming those are the only two uninvoiced transactions).
charge_now	boolean When set to true, the transaction will be automatically added to its own invoice and charged to the customers credit card. You will be alerted to any failures (i.e. if you have not connected a credit card processor, if the customer contact information is incomplete, etc.) Note that if the transaction is valid, it will ALWAYS be created, even though the charge may or may not fail. It is for this reason that when charge_now = true, Paid returns a 202 signaling the successful creation of the transaction and the asynchronous attempt to charge the customer.

Create a new transaction

DEFINITION
POST https://api.paidlabs.com/v0/transactions

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d customer_external_id=u12345 \
    -d amount=100 \
    -d "description=Designing awesome holiday cards." \
    -d metadata[promotion]=holiday_cards \
    -d metadata[discount]=bulk_100

EXAMPLE RESPONSE
{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "currency": "usd",
  "description": "Designing awesome holiday cards.",
  "customer": "cus_DLjf9aDKE9fkdncz",
  "metadata": {
    "promotion":"holiday_cards",
    "discount":"bulk_100"
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

DEFINITION
Paid::Transaction.create

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Transaction.create(
  :customer_external_id => "u12345",
  :amount => "100",
  :description => "Designing awesome holiday cards.",
  :metadata => {
    :promotion => "holiday_cards",
    :discount => "bulk_100"
  }
)

EXAMPLE RESPONSE
#<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Designing awesome holiday cards.",
  "customer": "cus_DLjf9aDKE9fkdncz",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Create a transaction by making a single call to the API. Transactions will be used to build invoices once they are assigned to a customer.

Arguments

Argument	Description
amount	required An amount in cents (i.e. $1.25 would be 125). Amounts can be negative (i.e. -247 could represent a $2.47 discount)
description	required This will appear on invoices as the line item description.
customer	optional either customer or customer_external_id is required
currency	optional
customer_external_id	optional either customer or customer_external_id is required
metadata	optional default is { } A hash of key/value pairs used for storing additional information about the transaction in a structured format.
rank	optional
serviced_on	date default is created_at The date displayed on the invoice.
service_starts_on	date default is created_at
service_ends_on	date default is created_at
charge_now	optional When set to true, the transaction will be automatically added to its own invoice and charged to the customers credit card. You will be alerted to any failures (i.e. if you have not connected a credit card processor, if the customer contact information is incomplete, etc.) Note that if the transaction is valid, it will ALWAYS be created, even though the charge may or may not fail. It is for this reason that when charge_now = true, Paid returns a 202 signaling the successful creation of the transaction and the asynchronous attempt to charge the customer.

Retrieve an existing transaction

DEFINITION
GET https://api.paidlabs.com/v0/transactions/{TRANSACTION_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions/tr_3fj38099dalkxie \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "currency": "usd",
  "description": "Designing awesome holiday cards.",
  "customer": "cus_83dkEOckd920dE",
  "metadata": {
    "promotion":"holiday_cards",
    "discount":"bulk_100"
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

DEFINITION
Paid::Transaction.retrieve({TRANSACTION_ID})

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Transaction.retrieve("tr_3fj38099dalkxie")

EXAMPLE RESPONSE
#<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Designing awesome holiday cards.",
  "customer": "cus_83dkEOckd920dE",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Retrieves the details of a transaction that has previously been created. Supply a unique transaction ID that was returned in a previous request.

You cannot update transactions that have been marked as paid.

Arguments

Argument	Description
id	required The identifier of the transaction to be retrieved.

Returns

Returns a transaction object if a valid identifier was provided, and returns an error otherwise.

Update a Transaction

DEFINITION
PUT https://api.paidlabs.com/v0/transactions/{TRANSACTION_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions/tr_3fj38099dalkxie \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d "description=Changing the description."

EXAMPLE RESPONSE
{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "currency": "usd",
  "description": "Changing the description.",
  "customer": "cus_83dkEOckd920dE",
  "metadata": {
    "promotion":"holiday_cards",
    "discount":"bulk_100"
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

DEFINITION
tr = Paid::Transaction.retrieve({TRANSACTION_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save

EXAMPLE REQUEST
require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

tr = Paid::Transaction.retrieve("tr_3fj38099dalkxie")
tr.description = "Changing the description"
tr.save

EXAMPLE RESPONSE
#<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Changing the description",
  "customer": "cus_83dkEOckd920dE",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Updates the specified transaction by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
amount	optional An amount in cents (i.e. $1.25 would be 125). Amounts can be negative (i.e. -247 could represent a $2.47 discount)
description	optional This will appear on invoices as the line item description.
customer	optional either customer or customer_external_id is required to be set
customer_external_id	optional either customer or customer_external_id is required to be set
metadata	optional default is { } A hash of key/value pairs used for storing additional information about the transaction in a structured format.
serviced_on	date default is created_at The date displayed on the invoice.
service_starts_on	date default is created_at
service_ends_on	date default is created_at
rank	optional
group_by	string This string is used when generating invoices. Only transactions with the same group_by will be placed on the same invoice. For example, if you create two transactions one with group_by = 'asdf' and the other with group_by = '1234', calling generate_invoices will return a list of two invoices (assuming those are the only two uninvoiced transactions).
charge_now	optional When set to true, the transaction will be automatically added to its own invoice and charged to the customers credit card. You will be alerted to any failures (i.e. if you have not connected a credit card processor, if the customer contact information is incomplete, etc.) Note that if the transaction is valid, it will ALWAYS be created, even though the charge may or may not fail. It is for this reason that when charge_now = true, Paid returns a 202 signaling the successful creation of the transaction and the asynchronous attempt to charge the customer.

List all transactions

DEFINITION
GET https://api.paidlabs.com/v0/transactions

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "tr_3fj38099dalkxie",
      "object": "transaction",
      "amount": 100,
      "currency": "usd",
      "description": "Designing awesome holiday cards.",
      "customer": "cus_83dkEOckd920dE",
      "metadata": {
        "promotion":"holiday_cards",
        "discount":"bulk_100"
      },
      "paid": false,
      "group_by": null,
      "paid_at": null,
      "serviced_on": 1433978417,
      "invoice": null
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Transaction.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Transaction.all(
:customer => "cus_DLjf9aDKE9fkdncz"

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
      "id": "tr_3fj38099dalkxie",
      "object": "transaction",
      "amount": 100,
      "description": "Designing awesome holiday cards.",
      "customer": "cus_83dkEOckd920dE",
      "paid": false,
      "group_by": null,
      "paid_at": null,
      "serviced_on": 1433978417,
      "metadata": {
      },
      "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
    },
    #<Paid::Transaction[...] ...>,
    #<Paid::Transaction[...] ...>
  ]
}

Returns a list of transactions you’ve previously created. The transactions are returned in sorted order, with the most recent transactions appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

Argument	Description
customer	optional Only return transactions for the customer specified by this customer ID.
invoice	optional Only return transactions for the invoice specified by this invoice ID.
created_at	optional A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp: gt for greater than gte for greater than or equal to lt for less than lte for less thank or equal to See datetime filter examples here.

See Pagination section for supported pagination arguments.

Delete a transaction

DEFINITION
DELETE https://api.paidlabs.com/v0/transactions/{TRANSACTION_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions/{TRANSACTION_ID} \
-u sk_test_nUbl45Q7BQhioCNVhSw: \
-x DELETE

EXAMPLE RESPONSE
{
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "currency": "usd",
  "description": "Changing the description.",
  "customer": "cus_83dkEOckd920dE",
  "metadata": {
    "promotion":"holiday_cards",
    "discount":"bulk_100"
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

DEFINITION
trx = Paid::Transaction.retrieve({TRANSACTION_ID})
trx.delete

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

trx = Paid::Transaction.retrieve("tr_3fj38099dalkxie")
trx.delete

EXAMPLE RESPONSE
#<Paid::Transaction id=tr_3fj38099dalkxie 0x00000a> JSON: {
  "id": "tr_3fj38099dalkxie",
  "object": "transaction",
  "amount": 100,
  "description": "Changing the description",
  "customer": "cus_83dkEOckd920dE",
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Deletes a transaction you’ve previously created.

Arguments

Argument	Description
id	required The identifier of the transaction to be deleted.

Returns

Returns a transaction object or an error.

Refund a transaction

DEFINITION
GET https://api.paidlabs.com/v0/transactions/:id/refunds

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/transactions/:id/refunds \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "rfnd_98sdfDFKd093jdSDs",
  "object": "refund",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "payment": "pay_sdlkf934jdfieDD3"
}

NOT AVAILABLE

Allows you to refund a transaction, automatically crediting the invoice for the transaction amount. Returns a refund. Please note that refunds are not directly associated to transactions. They are associated only to payments. This route is merely provided as a shortcut for refunding the amount of a transaction and applying a credit to the invoice.

Arguments

Argument	Description
amount optional	Defaults to the transaction amount.
credit_invoice optional	Defaults to false. When true, a credit (negative amount) transaction in the amount of the refund will be added to the invoice referencing the refund returned.
payment optional	Defaults to the the payment applied to the associated invoice if there is only one unrefunded payment currently applied to the invoice. If there are multiple refundable payments, you will need to specify a Payment ID.
process_using_paid boolean	Defaults to false. Some payments (i.e. credit cards processed using Paid) can also be refunded automatically by Paid. Simply pass true for this value.

Invoices

The invoice object

{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

EXAMPLE OBJECT
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Attributes

Parameter	Description
id	string
object	string value is “invoice”
amount	integer Amount in cents
summary	string Summary text to be included at the top of an invoice.
due_date	timestamp
customer	string
issued_at	timestamp
number	integer
paid	boolean
terms	integer The number of days from the Issue Date before the invoice is marked as overdue.
unpaid_amount	integer
overdue_amount	integer
url	string
metadata	metadata hash A hash of key/value pairs used for storing additional information about the transaction in a structured format.
views	integer
voided	boolean
voided_at	timestamp

Create an invoice

DEFINITION
POST https://api.paidlabs.com/v0/invoices

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/invoices \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d customer=cus_XJuvZeQXQgKMrpUAzPbGA

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Creates an invoice.

Arguments

Argument	Description
customer	required The identifier of an existing customer
summary	The summary that appears in the header of an invoice.

Returns

Returns a invoice object or returns an error otherwise.

Retrieve an existing invoice

DEFINITION
GET https://api.paidlabs.com/v0/invoices/{INVOICE_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiYnPE49XtN0A \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

DEFINITION
paid::Invoice.retrieve({INVOICE_ID})

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Invoice.retrieve("inv_8KAu1BU4PiYnPE49XtN0A")

EXAMPLE RESPONSE
EXAMPLE OBJECT
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Retrieves the details of a invoice that has previously been created. Supply a unique invoice ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the invoice to be retrieved.

Returns

Returns a invoice object if a valid identifier was provided, and returns an error otherwise.

Update an invoice

DEFINITION
PUT https://api.paidlabs.com/v0/invoices/{INVOICE_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiYnPE49XtN0A \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -X PUT \
    -d summary="This is a new summary."

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": "This is a new summary.",
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

DEFINITION
i = paid::Invoice.retrieve({INVOICE_ID})
i.summary = {NEW_SUMMARY}
...
i.save

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

i = Paid::Invoice.retrieve("inv_8KAu1BU4PiYnPE49XtN0A")
i.summary = "This is a new summary."
i.save

EXAMPLE RESPONSE
EXAMPLE OBJECT
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": "This is a new summary.",
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Updates the specified invoice by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
terms	optional
number	optional
charge_now	boolean
issue	boolean When true, this will issue the invoice.
send_communications	boolean Default: true. When false, communications (i.e. issue notices) will not be sent as a result of this request.
customer	string If you change the customer of an invoice, it, along with any transactions on the invoice, will be moved to the new customer. You cannot move an invoice for a number of reasons (i.e. there are payment applied to the invoice).
summary	optional
metadata	optional default is { } A hash of key/value pairs used for storing additional information about the transaction in a structured format. Set to nil to clear existing metadata.

Generate invoices

DEFINITION
POST https://api.paidlabs.com/v0/customers/{CUSTOMER_ID}/generate_invoices

EXAMPLE REQUEST

$ curl https://api.paidlabs.com/v0/customers/cus_XJuvZeQXQgKMrpUAzPbGA/generate_invoices \
   -u sk_test_nUbl45Q7BQhioCNVhSw: \
   -X POST

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "inv_8KAu1BU4PiYnPE49XtN0A",
      "summary": null,
      "terms": 30,
      "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
      "issued_at": null,
      "number": 10047,
      "paid": false,
      "metadata": {
      },
      "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
    },
    ...
  ]
}

DEFINITION
cu = Paid::Customer.retrieve({CUSTOMER_ID})
cu.generate_invoices

EXAMPLE REQUEST

require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

cu = Paid::Customer.retrieve("cus_XJuvZeQXQgKMrpUAzPbGA")
cu.generate_invoices

EXAMPLE RESPONSE
#<Paid::ListObject:0x3fe634d74498> JSON: {
  "object": "list",
  "data": [
    #<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
      "object": "invoice",
      "id": "inv_8KAu1BU4PiYnPE49XtN0A",
      "summary": null,
      "terms": 30,
      "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
      "issued_at": null,
      "number": 10047,
      "paid": false,
      "metadata": {
      },
      "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
    },
    ...
  ]
}

For customers on a 'manual' billing cycle, you can generate invoices via the API. All uninvoiced transactions will be added to the generated invoice. If there are no such transactions, an error will be returned.

This route always returns a list of invoices. Multiple invoices will be returned in the following scenarios:

1. You have uninvoiced transactions in multiple currencies. Currently, an invoice can containly only a single currency.

2. You specify multiple distinct group_by values on uninvoiced transactions. For example, if you create two transactions one with group_by = 'asdf' and the other with group_by = '1234', this route will return a list two invoices (assuming those are the only two uninvoiced transactions).

Arguments

Argument	Description
id	required The identifier of the customer you wish to generate an invoice for.

Returns

Returns a list object containing the new invoices. Generating invoices will fail if the customer is not set to a 'manual' billing cycle or the customer has no uninvoiced transactions, in which case the method will raise an error.

Issue an invoice

DEFINITION
POST https://api.paidlabs.com/v0/invoices/{INVOICE_ID}/issue

EXAMPLE REQUEST

$ curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiYnPE49XtN0A/issue \
   -u sk_test_nUbl45Q7BQhioCNVhSw: \
   -X POST

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": 1424607219,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

DEFINITION
inv = Paid::Invoice.retrieve({INVOICE_ID})
inv.issue

EXAMPLE REQUEST

require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

inv = Paid::Invoice.retrieve("inv_8KAu1BU4PiYnPE49XtN0A")
inv.issue

EXAMPLE RESPONSE
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": 1424607219,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Issuing an invoice sends the invoice to your customer. In most cases, you will use this as an approval process.

Arguments

Argument	Description
id	required The identifier of the invoice to be retrieved.

Returns

Returns a invoice object with an updated issued_at property. Issuing an invoice can fail if the invoice is already being issued or the invoice is already issued, in which case the method will raise an error.

Mark an invoice as paid

DEFINITION
POST https://api.paidlabs.com/v0/invoices/{INVOICE_ID}/mark_as_paid

EXAMPLE REQUEST

$ curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiYnPE49XtN0A/mark_as_paid \
   -u sk_test_nUbl45Q7BQhioCNVhSw: \
   -d via=ach \
   -X POST

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": true,
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

DEFINITION
inv = Paid::Invoice.retrieve({INVOICE_ID})
inv.mark_as_paid

EXAMPLE REQUEST

require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

inv = Paid::Invoice.retrieve("inv_8KAu1BU4PiYnPE49XtN0A")
inv.mark_as_paid(
  :via => 'ach'
)

EXAMPLE RESPONSE
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "number": 10047,
  "paid": true,
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Marking an invoice as paid will mark all associated payments as paid. You must supply the via attribute to help with future reconciliation.

Arguments

Argument	Description
id	required The identifier of the invoice to be marked as paid.
via	required Possible values include: ach, check, credit_card and wire

Returns

Returns a invoice object with an updated paid property. An invoice cannot be marked as paid unless it has been issued, in which case the method will raise an error.

Void an invoice

DEFINITION
POST https://api.paidlabs.com/v0/invoices/{INVOICE_ID}/void

EXAMPLE REQUEST

$ curl https://api.paidlabs.com/v0/invoices/inv_8KAu1BU4PiYnPE49XtN0A/void \
   -u sk_test_nUbl45Q7BQhioCNVhSw: \
   -X POST

EXAMPLE RESPONSE
{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": 1424607219,
  "voided_at": 1426552369,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

DEFINITION
inv = Paid::Invoice.retrieve({INVOICE_ID})
inv.void

EXAMPLE REQUEST

require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

inv = Paid::Invoice.retrieve("inv_8KAu1BU4PiYnPE49XtN0A")
inv.void

EXAMPLE RESPONSE
#<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": 1424607219,
  "voided_at": 1426552369,
  "paid": false,
  "metadata": {
  },
  "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
}

Voiding an invoice.

Arguments

Argument	Description
id	required The identifier of the invoice to be voided.

Returns

Returns a invoice object with an updated voided_at property. Voiding an invoice can fail if the invoice is already being voided or the invoice is already voided, in which case the method will raise an error.

List all invoices

DEFINITION
GET https://api.paidlabs.com/v0/invoices

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/invoices \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "inv_8KAu1BU4PiYnPE49XtN0A",
      "summary": null,
      "terms": 30,
      "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
      "issued_at": null,
      "number": 10047,
      "paid": false,
  "metadata": {
  },
      "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Invoice.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Invoice.all(
:customer => "cus_DLjf9aDKE9fkdncz"
:limit => 10

EXAMPLE RESPONSE
#<Paid::ListObject:0x3fe634d74498> JSON: {
    "object": "list",
  "data": [
    #<Paid::Invoice id=inv_8KAu1BU4PiYnPE49XtN0A 0x00000a> JSON: {
      "object": "invoice",
      "id": "inv_8KAu1BU4PiYnPE49XtN0A",
      "summary": null,
      "terms": 30,
      "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
      "issued_at": null,
      "number": 10047,
      "paid": false,
      "metadata": {
      },
      "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
    },
    #<Paid::Invoice[...] ...>,
    #<Paid::Invoice[...] ...>
  ]
}

Returns a list of invoices previously created. The invoices are returned in sorted order, with the most recent invoices appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

Payments

The payment object

{
  "id": "pay_sdlkf934jdfieDD3",
  "object": "payment",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "type": "ach"
}

Attributes

Parameter	Description
id	string
object	string value is “payment”
type	string
customer	string

Retrieve an existing payment

DEFINITION
GET https://api.paidlabs.com/v0/payments/{PAYMENT_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/payments/pay_sdlkf934jdfieDD3 \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "pay_sdlkf934jdfieDD3",
  "object": "payment",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "type": "ach"
}

Retrieves the details of a payment that has previously been created. Supply a unique payment ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the payment to be retrieved.

Returns

Returns a payment object if a valid identifier was provided, and returns an error otherwise.

List all payments

DEFINITION
GET https://api.paidlabs.com/v0/payments

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/payments \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "pay_sdlkf934jdfieDD3",
      "object": "payment",
      "amount": 100,
      "currency": "usd",
      "customer": "cus_83dkEOckd920dE",
      "type": "ach"
    },
    {  
      ...
    },
    {
      ...
    }
  ]
}

Returns a list of payments you’ve previously created. The payments are returned in sorted order, with the most recent payments appearing first. If no results are found given the arguments, an empty list should be returned.

See Pagination section for supported pagination arguments.

Argument	Description
customer optional	When provided, only payments applied to the customer will be returned.
invoice optional	When provided, only payments applied to the invoice will be returned.

Retrieve payment applications (beta)

DEFINITION
GET https://api.paidlabs.com/v0/payments/{PAYMENT_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/payments/pay_sdlkf934jdfieDD3 \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -G \
    -d 'include[]=payment_applications'

EXAMPLE RESPONSE
{
  "id": "pay_sdlkf934jdfieDD3",
  "object": "payment",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "type": "ach",
  "payment_applications": {
    "data": [
      {
        "amount": 100,
        "invoice": "inv_7L1REq5aG6Sh3YbH",
        "payment": "pay_sdlkf934jdfieDD3"
      }
    ],
    "object": "list",
    "total_pages": 1
  }
}

Retrieves a payment and include how the payment is applied. The payment_applications list object will include a list of hashes, each with an Invoice ID, Payment ID and the amount of that payment applied to the invoice.

Arguments

Argument	Description
id	required The identifier of the payment to be retrieved.

Returns

Returns a payment object if a valid identifier was provided, and returns an error otherwise.

Apply to invoices (beta)

DEFINITION
POST https://api.paidlabs.com/v0/payments/{PAYMENT_ID}/apply

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/payments/pay_sdlkf934jdfieDD3/apply \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d 'invoices[][id]=inv_1234567890' \
    -d 'invoices[][amount]=9995'

EXAMPLE RESPONSE
{
  "id": "pay_sdlkf934jdfieDD3",
  "object": "payment",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "type": "ach"
}

Applies a payment to the specified invoices in the invoices array. You can apply a payment to multiple invoices through the invoices array.

NOTE: When you apply a payment, previous applciations will be removed. If you intend to keep a payment applied to an invoice, you must include that invoice and the amount in the invoices array.

To retrieve how a payment is currently applied, see above.

Arguments

Argument	Description
invoices array	required Invoices is a list of hashes. Each hash must contain an id of an invoice and an amount of the payment you want to apply towards that invoice.
partial boolean	Paid will not automatically allow partial payments. If you have an invoice you want to partially pay with a payment, set this value to true.
notes string
external_reference_id string
external_cleared_on date

Returns

Returns a payment object, and returns an error otherwise.

Cards

The card object

{
  "id": "card_83jdjd93jdjDDF",
  "object": "card",
  "brand": "visa",
  "exp_month": 12,
  "exp_year": 2028,
  "stripe_card_id": "card_7DHFoiencosEK335",
  "customer": "cus_32y36dhCEfhd",
  "last4": "0384"
}

Attributes

Parameter	Description
id	string
object	string value is “card”
brand	string
exp_month	integer
exp_year	integer
stripe_card_id	string
customer	string
last4	string

Create a new card

DEFINITION
POST https://api.paidlabs.com/v0/customers/:customer_id/cards

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_32y36dhCEfhd/cards \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d stripe_card_id=card_7DHFoiencosEK335

EXAMPLE RESPONSE
{
  "id": "card_83jdjd93jdjDDF",
  "object": "card",
  "brand": "visa",
  "exp_month": 12,
  "exp_year": 2028,
  "stripe_card_id": "card_7DHFoiencosEK335",
  "customer": "cus_32y36dhCEfhd",
  "last4": "0384"
}

Create a card by making a single call to the API.

Arguments

Argument	Description
customer_id	required The identifier of the customer to add a card to.
stripe_card_id	required The ID of the card in Stripe. Be sure that the corresponding Stripe Customer ID is set on the Paid Customer.

Retrieve an existing card

DEFINITION
GET https://api.paidlabs.com/v0/customers/:customer_id/cards/:id

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_32y36dhCEfhd/cards/card_83jdjd93jdjDDF \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "card_83jdjd93jdjDDF",
  "object": "card",
  "brand": "visa",
  "exp_month": 12,
  "exp_year": 2028,
  "stripe_card_id": "card_7DHFoiencosEK335",
  "customer": "cus_32y36dhCEfhd",
  "last4": "0384"
}

Retrieves the details of a card that has previously been created. Supply a unique card ID that was returned in a previous request.

Arguments

Argument	Description
customer_id	required The identifier of the customer to add a card to.
id	required The identifier of the card to be retrieved.

Returns

Returns a card object if a valid identifier was provided, and returns an error otherwise.

List all transactions

DEFINITION
GET https://api.paidlabs.com/v0/customers/:customer_id/cards

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_32y36dhCEfhd/cards \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "card_83jdjd93jdjDDF",
      "object": "card",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2028,
      "stripe_card_id": "card_7DHFoiencosEK335",
      "customer": "cus_32y36dhCEfhd",
      "last4": "0384"
    },
    { ... },
    { ... },
  ]
}

Returns a list of cards you’ve previously created.

Arguments

Argument	Description
customer_id	required The identifier of the customer to add a card to.

See Pagination section for supported pagination arguments.

—

Plans

The plan object

{
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

EXAMPLE OBJECT
#<Paid::Plan id=pl_skBQYX4jmEE6VsTcRNkPg 0x00000a> JSON: {
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

Attributes

Parameter	Description
id	string
object	string value is “plan”
amount	integer Amount is in cents
currency	string
description	string This value is what will appear on an invoice when a transaction is created.
name	string This is a unique string identifier you can set for a plan.
interval	interval string One of day, week, month or year. The frequency with which a subscription should be billed.
interval_count	positive integer The number of intervals (specified in the interval property) between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.
metadata	metadata hash A hash of key/value pairs used for storing additional information about the plan in a structured format.

Create a new plan

DEFINITION
POST https://api.paidlabs.com/v0/plans

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/plans \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d amount=25000 \
    -d description="Quarterly platform fee" \
    -d name="quarterly-250" \
    -d interval="month" \
    -d interval_count=3

EXAMPLE RESPONSE
{
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

DEFINITION
Paid::Plan.create

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Plan.create(
  :amount => 25000,
  :description => "Quarterly platform fee",
  :name => "quarterly-250",
  :interval => "month",
  :interval_count => 3
)

EXAMPLE RESPONSE
#<Paid::Plan id=pl_skBQYX4jmEE6VsTcRNkPg 0x00000a> JSON: {
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

Create a plan by making a single call to the API. Plans are used to create subscriptions for customers.

Arguments

Argument	Description
amount	required Amount is in cents
description	required This value is what will appear on an invoice when a transaction is created.
name	required This is a unique string identifier you can set for a plan.
currency	optional Defaults to USD
interval	optional default is month One of day, week, month or year. The frequency with which a subscription should be billed.
interval_count	optional default is 1 The number of intervals (specified in the interval property) between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.

Retrieve an existing plan

DEFINITION
GET https://api.paidlabs.com/v0/plans/{PLAN_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/plans/pl_skBQYX4jmEE6VsTcRNkPg \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

DEFINITION
Paid::Plan.retrieve({PLAN_ID})

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Plan.retrieve("pl_skBQYX4jmEE6VsTcRNkPg")

EXAMPLE RESPONSE
#<Paid::Plan id=pl_skBQYX4jmEE6VsTcRNkPg 0x00000a> JSON: {
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Quarterly platform fee",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

Retrieves the details of a plan that has previously been created. Supply a unique plan ID that was returned in a previous request.

You cannot update plans that have been used in a subscription.

Arguments

Argument	Description
id	required The identifier of the plan to be retrieved.

Returns

Returns a plan object if a valid identifier was provided, and returns an error otherwise.

Update a Plan

DEFINITION
POST https://api.paidlabs.com/v0/plans/{PLAN_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/plans/pl_skBQYX4jmEE6VsTcRNkPg \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d description="Changing the description." \

EXAMPLE RESPONSE
{
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Changing the description",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

DEFINITION
tr = Paid::Plan.retrieve({PLAN_ID})
tr.description = {NEW_DESCRIPTION}
...
tr.save

EXAMPLE REQUEST
require "paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

tr = Paid::Plan.retrieve("pl_skBQYX4jmEE6VsTcRNkPg")
tr.description = "Changing the description"
tr.save

EXAMPLE RESPONSE
#<Paid::Plan id=pl_skBQYX4jmEE6VsTcRNkPg 0x00000a> {
  "object": "plan",
  "id": "pl_skBQYX4jmEE6VsTcRNkPg",
  "created_at": 1425264804,
  "description": "Changing the description",
  "name": "quarterly-250",
  "interval": "month",
  "interval_count": 3,
  "amount": 25000
}

Updates the specified plan by setting the values of the parameters passed. Any parameters not provided will be left unchanged. You cannot update plans that have been used in a subscription.

Arguments

Argument	Description
amount	optional Amount is in cents
description	optional This value is what will appear on an invoice when a transaction is created.
name	optional This is a unique string identifier you can set for a plan.
currency	optional Defaults to USD
interval	optional One of day, week, month or year. The frequency with which a subscription should be billed.

default is 1
The number of intervals (specified in the interval property) between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.

List all plans

DEFINITION
GET https://api.paidlabs.com/v0/plans

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/plans \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "plan",
      "id": "pl_skBQYX4jmEE6VsTcRNkPg",
      "created_at": 1425264804,
      "description": "Changing the description",
      "name": "quarterly-250",
      "interval": "month",
      "interval_count": 3,
      "amount": 25000
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Plan.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Plan.all

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Plan id=pl_skBQYX4jmEE6VsTcRNkPg 0x00000a> JSON: {
      "object": "plan",
      "id": "pl_skBQYX4jmEE6VsTcRNkPg",
      "created_at": 1425264804,
      "description": "Changing the description",
      "name": "quarterly-250",
      "interval": "month",
      "interval_count": 3,
      "amount": 25000
    },
    #<Paid::Plan[...] ...>,
    #<Paid::Plan[...] ...>
  ]
}

Returns a list of plans you’ve previously created. The plans are returned in sorted order, with the most recent plans appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

Argument	Description
created_at	optional A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp: gt for greater than gte for greater than or equal to lt for less than lte for less thank or equal to See datetime filter examples here.

See Pagination section for supported pagination arguments.

Subscriptions

The subscription object

{
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1426020560,
  "ended_at": 0,
  "cancelled_at": 0
}

EXAMPLE OBJECT
#<Paid::Subscription id=sub_iPmHnZbknJ5RYxQ2nMInw 0x00000a> JSON: {
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1426020560,
  "ended_at": 0,
  "cancelled_at": 0
}

Attributes

Parameter	Description
id	string
object	string value is “subscription”
customer	string
plan	hash plan object This is a unique string identifier you can set for a plan.
starts_on	date
started_at	datetime
ended_at	datetime
charge_now	boolean
cancelled_at	datetime

Create a new subscription

DEFINITION
POST https://api.paidlabs.com/v0/subscriptions

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/subscriptions \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d customer=cus_6QWastaltn1lTKEoGg \
    -d plan=pl_skBQYX4jmEE6VsTcRNkPg

EXAMPLE RESPONSE
{
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 0,
  "cancelled_at": 0
}

DEFINITION
Paid::Subscription.create

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Subscription.create(
  :customer => "cus_6QWastaltn1lTKEoGg",
  :plan => "pl_skBQYX4jmEE6VsTcRNkPg"
)

EXAMPLE RESPONSE
#<Paid::Subscription id=sub_iPmHnZbknJ5RYxQ2nMInw 0x00000a> JSON: {
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 0,
  "cancelled_at": 0
}

Create a subscription by making a single call to the API.

Arguments

Argument	Description
customer	required
plan	required
starts_on	optional default is now
charge_now	optional

Retrieve an existing subscription

DEFINITION
GET https://api.paidlabs.com/v0/subscriptions/{SUBSCRIPTION_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/subscriptions/sub_iPmHnZbknJ5RYxQ2nMInw \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 0,
  "cancelled_at": 0
}

DEFINITION
Paid::Subscription.retrieve({SUBSCRIPTION_ID})

EXAMPLE REQUEST
require "paid"
paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Subscription.retrieve("sub_iPmHnZbknJ5RYxQ2nMInw")

EXAMPLE RESPONSE
#<Paid::Subscription id=sub_iPmHnZbknJ5RYxQ2nMInw 0x00000a> JSON: {
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 0,
  "cancelled_at": 0
}

Retrieves the details of a subscription that has previously been created. Supply a unique subscription ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the subscription to be retrieved.

Returns

Returns a subscription object if a valid identifier was provided, and returns an error otherwise.

Cancel a subscription

DEFINITION
POST https://api.paidlabs.com/v0/subscriptions/{SUBSCRIPTION_ID}/cancel

EXAMPLE REQUEST

$ curl https://api.paidlabs.com/v0/subscriptions/inv_8KAu1BU4PiYnPE49XtN0A/cancel \
   -u sk_test_nUbl45Q7BQhioCNVhSw: \
   -X POST

EXAMPLE RESPONSE
{
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 1425971230,
  "cancelled_at": 1425971230
}

DEFINITION
inv = Paid::Subscription.retrieve({SUBSCRIPTION_ID})
inv.cancel

EXAMPLE REQUEST

require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

inv = Paid::Subscription.retrieve("sub_iPmHnZbknJ5RYxQ2nMInw")
inv.cancel

EXAMPLE RESPONSE
#<Paid::Subscription id=sub_iPmHnZbknJ5RYxQ2nMInw 0x00000a> JSON: {
  "object": "subscription",
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
  "created_at": 1425264818,
  "starts_on": 1425970800,
  "plan": {
    "object": "plan",
    "id": "pl_skBQYX4jmEE6VsTcRNkPg",
    "created_at": 1425264804,
    "description": "This is money we want every day.",
    "name": "Test Daily Plan",
    "interval": "day",
    "interval_count": 1,
    "amount": 1
  },
  "customer": "cus_6QWastaltn1lTKEoGg",
  "started_at": 1425970800,
  "ended_at": 1425971230,
  "cancelled_at": 1425971230
}

Cancelling a subscription will not affect any existing transactions. It will simply halt any further transactions being created as a result of the subscription.

Arguments

Argument	Description
id	required The identifier of the subscription to be cancelled.

Returns

Returns a subscription object with an updated cancelled_at property. Otherwise it will raise an error.

List all subscriptions

DEFINITION
GET https://api.paidlabs.com/v0/subscriptions

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/subscriptions \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "subscription",
      "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
      "created_at": 1425264818,
      "starts_on": 1425970800,
      "plan": {
        "object": "plan",
        "id": "pl_skBQYX4jmEE6VsTcRNkPg",
        "created_at": 1425264804,
        "description": "This is money we want every day.",
        "name": "Test Daily Plan",
        "interval": "day",
        "interval_count": 1,
        "amount": 1
      },
      "customer": "cus_6QWastaltn1lTKEoGg",
      "started_at": 1425970800,
      "ended_at": 0,
      "cancelled_at": 0
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Subscription.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Subscription.all

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Subscription id=sub_iPmHnZbknJ5RYxQ2nMInw 0x00000a> JSON: {
      "object": "subscription",
      "id": "sub_iPmHnZbknJ5RYxQ2nMInw",
      "created_at": 1425264818,
      "starts_on": 1425970800,
      "plan": {
        "object": "plan",
        "id": "pl_skBQYX4jmEE6VsTcRNkPg",
        "created_at": 1425264804,
        "description": "This is money we want every day.",
        "name": "Test Daily Plan",
        "interval": "day",
        "interval_count": 1,
        "amount": 1
      },
      "customer": "cus_6QWastaltn1lTKEoGg",
      "started_at": 1425970800,
      "ended_at": 0,
      "cancelled_at": 0
    },
    #<Paid::Subscription[...] ...>,
    #<Paid::Subscription[...] ...>
  ]
}

Returns a list of subscriptions you’ve previously created. The subscriptions are returned in sorted order, with the most recent subscriptions appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

Argument	Description
created_at	optional A filter on the list based on the object created_at field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with the following options, all of which take a string with an integer Unix timestamp: gt for greater than gte for greater than or equal to lt for less than lte for less thank or equal to See datetime filter examples here.

See Pagination section for supported pagination arguments.

—

Users

The user object

{
  "id": "user_o6nNVSPNI61JrIb0Aalzw",
  "object": "user",
  "email": "hello@paidlabs.com",
  "first_name": "Ryan",
  "last_name": "Jackson",
  "created_at": "1452728157"
}

IN DEVELOPMENT

Attributes

Parameter	Description
id	string
object	string
email	string
first_name	string
last_name	string

See Event Types section for supported event arguments.

Create a new user

DEFINITION
POST https://api.paidlabs.com/v0/users

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/users \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d first_name='Ryan' \
    -d email='test@paidlabs.com' \
    -X POST \

EXAMPLE RESPONSE
{
  "id": "user_o6nNVSPNI61JrIb0Aalzw",
  "object": "user",
  "email": "hello@paidlabs.com",
  "first_name": "Ryan",
  "last_name": "Jackson",
  "created_at": "1452728157"
}

IN DEVELOPMENT

Create a user for current account

See Event Types section for supported event arguments.

Arguments

Argument	Description
email	required
first_name	required
last_name	optional
password	optional

Retrieve an existing user

DEFINITION
GET https://api.paidlabs.com/v0/users/{USER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/users/usr_MFN1aqPE7iZBJhf8h4l9A \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "user_o6nNVSPNI61JrIb0Aalzw",
  "object": "user",
  "email": "hello@paidlabs.com",
  "first_name": "Ryan",
  "last_name": "Jackson",
  "created_at": "1452728157"
}

IN DEVELOPMENT

Retrieves the details of a user that has previously been created

Arguments

Argument	Description
id	required The identifier of the user to be retrieved.

Returns

Returns a user object if a valid identifier was provided, and returns an error otherwise.

Update a user

DEFINITION
PUT https://api.paidlabs.com/v0/users/{USER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/users/usr_MFN1aqPE7iZBJhf8h4l9A \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d first_name='Bob'

EXAMPLE RESPONSE
{
  "id": "user_o6nNVSPNI61JrIb0Aalzw",
  "object": "user",
  "email": "hello@paidlabs.com",
  "first_name": "Bob",
  "last_name": "Jackson",
  "created_at": "1452728157"
}

IN DEVELOPMENT

Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
email	required
first_name	required
last_name	optional
password	optional

List all users

DEFINITION
GET https://api.paidlabs.com/v0/users

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/users \
-u sk_live_wplKzJA5nQMWKVaRizTcuQ:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "hook_o6nNVSPNI61JrIb0Aalzw",
      "object": "webhook",
      "url": "https://zapier.com/hooks/standard/88202c8decdc4a2e9c5e31f33d6fe6bc/",
      "event": "customer.created",
      "created_at": "1452728157",
      "updated_at": "1452728157"
    },
    { ... },
    { ... },
  ]
}

IN DEVELOPMENT

Returns a list of users associated with the account.

Delete a user

DEFINITION
DELETE https://api.paidlabs.com/v0/user/{USER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/user/{USER_ID} \
-u sk_test_nUbl45Q7BQhioCNVhSw: \
-x DELETE

EXAMPLE RESPONSE
{
  "id": "hook_o6nNVSPNI61JrIb0Aalzw",
  "object": "webhook",
  "url": "https://zapier.com/hooks/standard/88202c8decdc4a2e9c5e31f33d6fe6bc/",
  "event": "customer.created",
  "created_at": "1452728157",
  "updated_at": "1452728157"
}

IN DEVELOPMENT

Deletes a user you’ve previously created.

Arguments

Argument	Description
id	required The identifier of the user to be deleted.

Returns

Returns a user object or an error.

Events

The event object

{
  "object": "event",
  "id": "evt_b8DZtUtZs8sxs0EsCcMg",
  "type":"invoice.generated",
  "created_at":1421719697,
  "data": {
    "object": "invoice",
    "id": "inv_8KAu1BU4PiYnPE49XtN0A",
    "summary": null,
    "terms": 30,
    "customer": "cus_0_4",
    "issued_at": null,
    "paid": false,
    "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
  }
}

#<Paid::Event id=evt_b8DZtUtZs8sxs0EsCcMg 0x00000a> JSON: {
  "object": "event",
  "id": "evt_b8DZtUtZs8sxs0EsCcMg",
  "type":"invoice.generated",
  "created_at":1421719697,
  "data": {
    "object": "invoice",
    "id": "inv_8KAu1BU4PiYnPE49XtN0A",
    "summary": null,
    "terms": 30,
    "customer": "cus_0_4",
    "issued_at": null,
    "paid": false,
    "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
  }
}

attributes

Parameter	Description
id	string
object	string value is “event”
created_at	integer
type	string The type of event that was created. In this case, an invoice was generated.
data	object This will be the object the event references. In this case, an invoice.

Retrieve an existing event

DEFINITION
GET https://api.paidlabs.com/v0/events/{EVENT_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/events/evt_b8DZtUtZs8sxs0EsCcMg \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "event",
  "id": "evt_b8DZtUtZs8sxs0EsCcMg",
  "type":"invoice.generated",
  "created_at":1421719697,
  "data": {
    "object": "invoice",
    "id": "inv_8KAu1BU4PiYnPE49XtN0A",
    "summary": null,
    "terms": 30,
    "customer": "cus_0_4",
    "issued_at": null,
    "paid": false,
    "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
  }
}

DEFINITION
Paid::Event.retrieve({EVENT_ID})

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Event.retrieve("evt_b8DZtUtZs8sxs0EsCcMg")

EXAMPLE RESPONSE
#<Paid::Event id=evt_b8DZtUtZs8sxs0EsCcMg 0x00000a> JSON: {
  "object": "event",
  "id": "evt_b8DZtUtZs8sxs0EsCcMg",
  "type":"invoice.generated",
  "created_at":1421719697,
  "data": {
    "object": "invoice",
    "id": "inv_8KAu1BU4PiYnPE49XtN0A",
    "summary": null,
    "terms": 30,
    "customer": "cus_0_4",
    "issued_at": null,
    "paid": false,
    "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
  }
}

Retrieves the details of a event that has previously been created. Supply a unique event ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the event to be retrieved.

Returns

Returns a event object if a valid identifier was provided, and returns an error otherwise.

List all events

DEFINITION
GET https://api.paidlabs.com/v0/events

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/events \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_b8DZtUtZs8sxs0EsCcMg",
      "type":"invoice.generated",
      "created_at":1421719697,
      "data": {
        "object": "invoice",
        "id": "inv_8KAu1BU4PiYnPE49XtN0A",
        "summary": null,
        "terms": 30,
        "customer": "cus_0_4",
        "issued_at": null,
        "paid": false,
        "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
      }
    },
    { ... },
    { ... },
  ]
}

DEFINITION
Paid::Event.all

EXAMPLE REQUEST
require "Paid"
Paid.api_key = "sk_test_nUbl45Q7BQhioCNVhSw"

Paid::Event.all

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    #<Paid::Event id=evt_b8DZtUtZs8sxs0EsCcMg 0x00000a> JSON: {
      "object": "event",
      "id": "evt_b8DZtUtZs8sxs0EsCcMg",
      "type":"invoice.generated",
      "created_at":1421719697,
      "data": {
        "object": "invoice",
        "id": "inv_8KAu1BU4PiYnPE49XtN0A",
        "summary": null,
        "terms": 30,
        "customer": "cus_0_4",
        "issued_at": null,
        "paid": false,
        "url": "https://payments.paidlabs.com/invoices/inv_8KAu1BU4PiYnPE49XtN0A"
      }
    },
    #<Paid::Event[...] ...>,
    #<Paid::Event[...] ...>,
  ]
}

Returns a list of events previously created. The events are returned in sorted order, with the most recent events appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

Event Types

Here is a list of all the different event types. If you want to request an event type that is not in this list, please contact hello@paidlabs.com

Types

• ‘invoice.card.error’
• ‘invoice.generated’
• ‘invoice.issued’
• ‘invoice.paid’
• ‘invoice.payment.intended’
• ‘customer.new-stripe-id’
• ‘customer.created’
• ‘transaction.created’
• ‘transaction.paid’
• ‘transaction.voided’
• ‘report.created’

—

Idempotent Requests (Beta)

$ curl https://api.paidlabs.com/v0/transactions \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -H "Idempotency-Key: KYlo2CVtPkFKZ6" \
    -d customer=cus_SDKf034ufdkjdf93k \
    -d amount=100 \
    -d "description=Testing idempotency."

Paid’s API supports idempotent requests enabling you to retry requests without accidentally running the same operation more than once. For example, if you’re creating a transaction and something fails, you can retry the same request with the same idempotency key to ensure you only create a single transaction.

You can perform idempotent requests on any POST request using an Idempotency-Key: <idempotency_key> header.

Your key can be any string you want, so long as it is unique per request. We suggest random strings, internal unique IDs, UUIDs, etc.

A few things to note:

• Paid will return the same response for any subsequent request using the same key. (Note: We will not return an error.)
• You cannot use the same key for different request routes or parameters.
• Keys expire after 24 hours.

Statements (Beta)

The statement object

{
  "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
  "object": "statement",
  "resource": "cus_DLjf9aDKE9fkdncz",
  "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
  "expires_on": 1490832000,
  "expired_at": null
}

Attributes

Parameter	Description
id	string
object	string value is “statement”
resource	string The resource the statment is for.
url	string Unique URL to this statement.
expires_on	integer The date the statement expires and will no longer be accessible.
expires_at	integer The time the statement was manually expired.

Create a new customer statement

DEFINITION
POST https://api.paidlabs.com/v0/customers/{CUSTOMER_ID}/statements

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_DLjf9aDKE9fkdncz/statements \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
  "object": "statement",
  "resource": "cus_DLjf9aDKE9fkdncz",
  "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
  "expires_on": 1490832000,
  "expired_at": null
}

Create a customer statement by making a single call to the API.

Arguments

Argument	Description
expires_on	optional Defaults to 1 week from today.

Retrieve an existing statement

DEFINITION
GET https://api.paidlabs.com/v0/statements/{STATEMENT_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/statements/stmt_cN7rs6Nk7LYlVVyQLnCw \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
  "object": "statement",
  "resource": "cus_DLjf9aDKE9fkdncz",
  "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
  "expires_on": 1490832000,
  "expired_at": null
}

Retrieves the details of a statement that has previously been created. Supply a unique statement ID that was returned in a previous requests

Arguments

Argument	Description
id	required The identifier of the statement to be retrieved.

Returns

Returns a statement object if a valid identifier was provided, and returns an error otherwise.

Update a statement

DEFINITION
PUT https://api.paidlabs.com/v0/statements/{CUSTOMER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/statements/stmt_cN7rs6Nk7LYlVVyQLnCw \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d expires_on=1490918400 \

EXAMPLE RESPONSE
{
  "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
  "object": "statement",
  "resource": "cus_DLjf9aDKE9fkdncz",
  "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
  "expires_on": 1490918400,
  "expired_at": null
}

Updates the specified statement by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
expires_on	optional

List all statements for a customer

DEFINITION
GET https://api.paidlabs.com/v0/customers/{CUSTOMER_ID}/statements

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/customers/cus_DLjf9aDKE9fkdncz/statements \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
      "object": "statement",
      "resource": "cus_DLjf9aDKE9fkdncz",
      "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
      "expires_on": 1490918400,
      "expired_at": null
    },
    { ... },
    { ... },
  ]
}

Returns a list of all statements you’ve previously created. The statements are returned in sorted order, with the most recent statements appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

List all statements

DEFINITION
GET https://api.paidlabs.com/v0/statements

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/statements \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "stmt_cN7rs6Nk7LYlVVyQLnCw",
      "object": "statement",
      "resource": "cus_DLjf9aDKE9fkdncz",
      "url": "https://secure.paidlabs.com/statements/stmt_cN7rs6Nk7LYlVVyQLnCw",
      "expires_on": 1490918400,
      "expired_at": null
    },
    { ... },
    { ... },
  ]
}

Returns a list of all statements you’ve previously created. The statements are returned in sorted order, with the most recent statements appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

Organizations (Beta)

The organization object

{
  "created_at": 1490562059,
  "object": "organization",
  "id": "org_jWNJgsKGpnaM8G14FL2A",
  "updated_at": 1490562059,
  "external_id": null,
  "name": "Big Corporation, Inc."
}

Attributes

Parameter	Description
id	string
object	string value is “organization”
external_id	string
name	string

Create a new organization

DEFINITION
POST https://api.paidlabs.com/v0/organizations

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/organizations \
    -u sk_test_nUbl45Q7BQhioCNVhSw:
    -d "name=Big Corporation, Inc."

EXAMPLE RESPONSE
{
  "created_at": 1490562059,
  "object": "organization",
  "id": "org_jWNJgsKGpnaM8G14FL2A",
  "updated_at": 1490562059,
  "external_id": null,
  "name": "Big Corporation, Inc."
}

Create an organization by making a single call to the API.

Arguments

Argument	Description
external_id	optional
name	required

Retrieve an existing organization

DEFINITION
GET https://api.paidlabs.com/v0/organizations/{ORGANIZATION_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/organizations/org_jWNJgsKGpnaM8G14FL2A \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "created_at": 1490562059,
  "object": "organization",
  "id": "org_jWNJgsKGpnaM8G14FL2A",
  "updated_at": 1490562059,
  "external_id": null,
  "name": "Big Corporation, Inc."
}

Retrieves the details of an organization that has previously been created. Supply a unique organization ID that was returned in a previous requests

Arguments

Argument	Description
id	required The identifier of the organization to be retrieved.

Returns

Returns an organization object if a valid identifier was provided, and returns an error otherwise.

Update an organization

DEFINITION
PUT https://api.paidlabs.com/v0/organizations/{CUSTOMER_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/organizations/org_jWNJgsKGpnaM8G14FL2A \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d external_id=abcd123 \

EXAMPLE RESPONSE
{
  "created_at": 1490562059,
  "object": "organization",
  "id": "org_jWNJgsKGpnaM8G14FL2A",
  "updated_at": 1490562059,
  "external_id": "abcd123",
  "name": "Big Corporation, Inc."
}

Updates the specified organization by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

Arguments

Argument	Description
external_id	optional
name	optional
create boolean	optional When set to true, the {CUSTOMER_ID} in the request route is assumed to be the external_id of the organization. If the organization does not exist, Paid will automatically create one. This functionality allows you to create or update in the same route. Note: You CANNOT update the external_id when using the current external_id to update a resource (i.e. when {CUSTOMER_ID} == external_id).

List all organizations

DEFINITION
GET https://api.paidlabs.com/v0/organizations

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/organizations \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "created_at": 1490562059,
      "object": "organization",
      "id": "org_jWNJgsKGpnaM8G14FL2A",
      "updated_at": 1490562059,
      "external_id": null,
      "name": "Big Corporation, Inc."
    },
    { ... },
    { ... },
  ]
}

Returns a list of all organizations you’ve previously created. The organizations are returned in sorted order, with the most recent organizations appearing first. If no results are found given the arguments, an empty list should be returned.

Arguments

See Pagination section for supported pagination arguments.

Refunds (beta)

The refund object

{
  "id": "rfnd_98sdfDFKd093jdSDs",
  "object": "refund",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "type": "ach"
}

Attributes

Parameter	Description
id	string
object	string value is “refund”
type	string
payment	string
customer	string

Create a refund

DEFINITION
POST https://api.paidlabs.com/v0/payments/{PAYMENT_ID}/refunds

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/payments/pay_sdlkf934jdfieDD3/refunds \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d amount=100

EXAMPLE RESPONSE
{
  "id": "rfnd_98sdfDFKd093jdSDs",
  "object": "refund",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "payment": "pay_sdlkf934jdfieDD3"
}

Create a refund by making a single call to the API.

Note: You can only refund up to the amount of the payment that is unapplied to invoices and previous refunds. See (Payment Application)[#apply-to-invoices-beta] to unapply a payment.

Arguments

Argument	Description
amount integer	required An amount in cents (i.e. $1.25 would be 125) to refund.
process_using_paid boolean	Defaults to false. Some payments (i.e. credit cards processed using Paid) can also be refunded automatically by Paid. Simply pass true for this value.

Retrieve an existing refund

DEFINITION
GET https://api.paidlabs.com/v0/refunds/{PAYMENT_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/refunds/rfnd_98sdfDFKd093jdSDs \
    -u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "id": "rfnd_98sdfDFKd093jdSDs",
  "object": "refund",
  "amount": 100,
  "customer": "cus_83dkEOckd920dE",
  "payment": "pay_sdlkf934jdfieDD3"
}

Retrieves the details of a refund that has previously been created. Supply a unique refund ID that was returned in a previous request.

Arguments

Argument	Description
id	required The identifier of the refund to be retrieved.

Returns

Returns a refund object if a valid identifier was provided, and returns an error otherwise.

List all refunds

DEFINITION
GET https://api.paidlabs.com/v0/refunds

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/refunds \
-u sk_test_nUbl45Q7BQhioCNVhSw:

EXAMPLE RESPONSE
{
  "object": "list",
  "data": [
    {
      "id": "rfnd_98sdfDFKd093jdSDs",
      "object": "refund",
      "amount": 100,
      "currency": "usd",
      "customer": "cus_83dkEOckd920dE",
      "payment": "pay_sdlkf934jdfieDD3"
    },
    { ... },
    { ... },
  ]
}

Returns a list of refunds you’ve previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. If no results are found given the arguments, an empty list should be returned.

See Pagination section for supported pagination arguments.