NAV Navbar
Logo
cURL ruby

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 or 415.506.9330.

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!

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.
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.

Schedules

Paid API uses specially formatted schedules allowing you to fully customize when actions are triggered. All schedules follow the same format. A schedule is a list of integers (positive and negative) and an optional “repeater”.

We do not currently enforce though we HIGHLY recommend that you order your numbers from lowest to highest.

The repeater allows you to specify an interval over which the schedule will repeat. You can only use one repeater, and it must appear at the end of the schedule. A repeater is a string that starts with ~ and ends with a positive integer. For example, ~7 represents every 7 days from the last computed date in the schedule.

Paid schedules are all relative to a particular date, which will always be specified in the documentation.

A well-formatted and the default schedule for chase emails is the following [-7, -1, 0, 1, 5, 10, 15, 20, 25, 30, '~3']. The integers can also be passed as strings. Assuming that this schedule is relative to the date February 18, 2015 (say the due date of an invoice), this schedule would cause chase emails to be sent on the following dates:

2015-02-11
2015-02-17
2015-02-18
2015-02-19
2015-02-23
2015-02-28
2015-03-05
2015-03-10
2015-03-15
2015-03-20
every 3 days from 2015-03-20 until paid

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

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",
  "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",
  "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
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",
  "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",
  "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
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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "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
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",
  "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",
  "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
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",
      "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",
      "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",
      "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.

Events

The event object

{
  "object": "event",
  "id": "evt_b8DZtUtZs8sxs0EsCcMg",
  "type":"invoice.generated",
  "created_at":1421719697,
  "data": {
    "object": "invoice",
    "id": "inv_8KAu1BU4PiYnPE49XtN0A",
    "summary": null,
    "chase_schedule": [
      "-7",
      "-1",
      "0",
      "1",
      "5",
      "10",
      "15",
      "20",
      "25",
      "30",
      "~1"
    ]
    "next_chase_on": 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,
    "chase_schedule": [
      "-7",
      "-1",
      "0",
      "1",
      "5",
      "10",
      "15",
      "20",
      "25",
      "30",
      "~1"
    ]
    "next_chase_on": 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,
    "chase_schedule": [
      "-7",
      "-1",
      "0",
      "1",
      "5",
      "10",
      "15",
      "20",
      "25",
      "30",
      "~1"
    ]
    "next_chase_on": 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,
    "chase_schedule": [
      "-7",
      "-1",
      "0",
      "1",
      "5",
      "10",
      "15",
      "20",
      "25",
      "30",
      "~1"
    ]
    "next_chase_on": 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,
        "chase_schedule": [
          "-7",
          "-1",
          "0",
          "1",
          "5",
          "10",
          "15",
          "20",
          "25",
          "30",
          "~1"
        ]
        "next_chase_on": 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,
        "chase_schedule": [
          "-7",
          "-1",
          "0",
          "1",
          "5",
          "10",
          "15",
          "20",
          "25",
          "30",
          "~1"
        ]
        "next_chase_on": 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

Invoices

The invoice object


{
  "object": "invoice",
  "id": "inv_8KAu1BU4PiYnPE49XtN0A",
  "summary": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "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,
  "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
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

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,
  "chase_schedule": [
    "-7",
    "-1",
    "0",
    "1",
    "5",
    "10",
    "15",
    "20",
    "25",
    "30",
    "~1"
  ],
  "next_chase_on": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "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,
  "chase_schedule": [
    "-7",
    "-1",
    "0",
    "1",
    "5",
    "10",
    "15",
    "20",
    "25",
    "30",
    "~1"
  ],
  "next_chase_on": null,
  "terms": 30,
  "customer": "cus_XJuvZeQXQgKMrpUAzPbGA",
  "issued_at": null,
  "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,
  "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,
  "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
customer string
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,
      "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,
      "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,
  "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,
  "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,
      "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,
      "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.

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.

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.
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
paid_at optional default is today when marked paid
Set the date the transaction was paid off. Will default to the current date when the transaction is marked as paid. Format: ‘YYYY-MM-DD’ as a string.
serviced_on date default is created_at
The date displayed on the invoice.
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.
paid_at optional default is today when marked paid
Set the date the transaction was paid off. Will default to the current date when the transaction is marked as paid. Format: ‘YYYY-MM-DD’ as a string.
serviced_on date default is created_at
The date displayed on the invoice.
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.

Mark a transaction as paid

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

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

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": true,
  "group_by": null,
  "paid_at": "2015-02-25",
  "serviced_on": 1433978417,
  "invoice": null
}

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

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

t = Paid::Transaction.retrieve("tr_3fj38099dalkxie")
t.mark_as_paid

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": true,
  "group_by": null,
  "paid_at": "2015-02-25",
  "serviced_on": 1433978417,
  "metadata": {
  },
  "invoice": "inv_UkJafJKePJJktHZqgzdMnw"
}

Mark a transaction as paid. If this transaction is on an invoice, it won’t be included in the total amount due.

Arguments

Argument Description
id required
The identifier of the transaction to be retrieved.
paid_at optional default is today when marked paid
Set the date the transaction was paid off. Will default to the current date when the transaction is marked as paid. Format: ‘YYYY-MM-DD’ as a string.

Returns

Returns a transaction object with updated paid and paid_at metadata. You cannot mark an already-paid transaction as paid, which will result in an error.

Refund a transaction

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

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

EXAMPLE RESPONSE
{
  "id": "tr_asdf93os9Dkd983",
  "object": "transaction",
  "amount": -100,
  "currency": "usd",
  "description": "Refund for: Designing awesome holiday cards.",
  "customer": "cus_83dkEOckd920dE",
  "metadata": {
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

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

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

trx = Paid::Transaction.retrieve("tr_3fj38099dalkxie")
trx.refunds.create

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

Refund a transaction. You can only refund up to the total amount of the transaction. You cannot refund transactions with negative amounts.

Paid By Credit Card

If the transaction was paid via credit card, the card will automatically be refunded. In this case, the transaction will also automatically be added to the original invoice and marked as paid.

Paid by ACH, Check or Wire

If a transaction was paid by any method other than credit card, the resulting refund will not be assigned to any invoice. It will be rolled into the next generated invoice.

Arguments

Argument Description
id required
The identifier of the transaction to be refunded.
amount optional default is remaining refundable amount
Must be a positive integer. The default is the remaining refundable amount meaning the full amount less any existing partial refunds.

Returns

Returns a transaction object with a negative amount property or an error.

Void a transaction

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

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

EXAMPLE RESPONSE
{
  "id": "tr_asdf93os9Dkd983",
  "object": "transaction",
  "amount": -100,
  "currency": "usd",
  "customer": "cus_83dkEOckd920dE",
  "metadata": {
  },
  "paid": false,
  "group_by": null,
  "paid_at": null,
  "serviced_on": 1433978417,
  "invoice": null
}

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

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

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

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

Void a transaction.

Arguments

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

Returns

Returns a transaction object

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
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.

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.

Webhooks

The webhook object

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

IN DEVELOPMENT

Attributes

Parameter Description
id string
object string value is “webhook”
url integer
URL to ping for webhook
event string
Event for when to ping webhook. See Event Types section for supported event arguments.
created_at integer
updated_at integer

See Event Types section for supported event arguments.

Create a new webhook

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

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/webhooks \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d url='https://zapier.com/hooks/standard/88202c8decdc4a2e9c5e31f33d6fe6bc/' \
    -X POST \

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

IN DEVELOPMENT

Create a webhook by making a single call to the API. Webhooks will be pinged when their event occurs within Paid.

See Event Types section for supported event arguments.

Arguments

Argument Description
url required
A URL that will be pinged upon event
subscription_url optional
event optional
Event for when to ping webhook

Retrieve an existing webhook

DEFINITION
GET https://api.paidlabs.com/v0/webhooks/{WEBHOOK_ID}

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

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

IN DEVELOPMENT

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 webhook

DEFINITION
PUT https://api.paidlabs.com/v0/webhooks/{WEBHOOK_ID}

EXAMPLE REQUEST
$ curl https://api.paidlabs.com/v0/webhooks/hook_o6nNVSPNI61JrIb0Aalzw \
    -u sk_test_nUbl45Q7BQhioCNVhSw: \
    -d url='http://www.newurl.com/' \
    -d event='new.event'

EXAMPLE RESPONSE
{
  "id": "hook_o6nNVSPNI61JrIb0Aalzw",
  "object": "webhook",
  "url": "http://www.newurl.com/",
  "event": "new.event",
  "created_at": "1452728157",
  "updated_at": "1452728157"
}

IN DEVELOPMENT

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

Arguments

Argument Description
url optional
A URL that will be pinged upon event
subscription_url optional
event optional
Event for when to ping webhook

List all webhooks

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

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

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

IN DEVELOPMENT

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

Delete a webhook

DEFINITION
DELETE https://api.paidlabs.com/v0/webhooks/{WEBHOOK_ID}

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

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

IN DEVELOPMENT

Deletes a webhook you’ve previously created.

Arguments

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

Returns

Returns a webhook object or an error.

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

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.