Business API Reference

This is an object representing a business account. A business account is a Crater Invoice account that can accept payments from customers and pay out to connected bank account. A business can be a customer, vendor or both.

The Business model

The business model is the nucleus of operations, managing customers, estimates, and invoices. It orchestrates seamless financial transactions, ensuring effective customer engagement and revenue tracking. A centralized hub for streamlined business processes.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the business.

  • Name
    name
    Type
    string
    Description

    Name of the business.

  • Name
    email
    Type
    string
    Description

    Email of the business.

  • Name
    logo
    Type
    string
    Description

    Logo of the business.

  • Name
    website
    Type
    string
    Description

    Website of the business.

  • Name
    phone
    Type
    string
    Description

    Phone number of the business.

  • Name
    contact_first_name
    Type
    string
    Description

    First name of the business.

  • Name
    contact_last_name
    Type
    string
    Description

    Last name of the business.

  • Name
    payouts_enabled
    Type
    boolean
    Description

    Whether the business is enabled for payouts.

  • Name
    business_type
    Type
    string
    Description

    Type of the business.

  • Name
    billing_address
    Type
    object
    Description

    Billing address of the business.

  • Name
    shipping_address
    Type
    object
    Description

    Shipping address of the business.

  • Name
    created_at
    Type
    integer
    Description

    Timestamp when the business was created.

  • Name
    updated_at
    Type
    integer
    Description

    Timestamp when the business was last updated.

GETapi/v2/businesses

List all businesses

This endpoint allows you to retrieve a paginated list of all businesses on the platform.

Optional Parameters

  • Name
    limit
    Type
    integer
    Description

    Limit the number of businesses returned.

  • Name
    page
    Type
    integer
    Description

    Page number (for pagination).

  • Name
    name
    Type
    string
    Description

    Filter matching records by name.

  • Name
    business_type
    Type
    string
    Description

    Filter matching records by business_type.

  • Name
    email
    Type
    string
    Description

    Filter matching records by email.

  • Name
    phone
    Type
    string
    Description

    Filter matching records by phone.

  • Name
    contact_first_name
    Type
    string
    Description

    Filter matching records by contact_first_name.

  • Name
    contact_last_name
    Type
    string
    Description

    Filter matching records by contact_last_name.

Request

GET
api/v2/businesses
curl --request GET \
  --get "https://payments.your-domain.com/api/v2/businesses" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response

{
  "data": [
    {
      "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "name": "XYZ Business",
      "website": null,
      "phone": null,
      "email": "john@xyz.com",
      "logo_url": null,
      "contact_first_name": "John",
      "contact_last_name": "Doe",
      "payouts_enabled": false,
      "business_type": "company",
      "created_at": 1683292509,
      "timezone": "America/New_York",
      "underwriting_status": {
        "bnpl": "PENDING",
        "factoring": "PENDING"
      },
    },
    {
      "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "name": "ABC Business",
      "website": null,
      "phone": null,
      "email": "jane@abc.com",
      "logo_url": null,
      "contact_first_name": "Jane",
      "contact_last_name": "Doe",
      "payouts_enabled": false,
      "business_type": "company",
      "created_at": 1683292509,
      "timezone": "America/New_York",
      "underwriting_status": {
        "bnpl": "PENDING",
        "factoring": "PENDING"
      },
    }
  ]
}
POSTapi/v2/businesses

Create a business

This endpoint allows you to create a new business.

Parameters

  • Name
    name
    Type
    string
    Description

    Name for the business.

  • Name
    email
    Type
    string
    Description

    Email of the business.

  • Name
    contact_first_name
    Type
    string
    Description

    First Name of the owner.

  • Name
    contact_last_name
    Type
    string
    Description

    Last Name of the owner.

  • Name
    business_type
    Type
    string
    Description

    Type of business. (individual or company)

Optional Parameters

  • Name
    phone
    Type
    string
    Description

    Business phone number.

  • Name
    website
    Type
    string
    Description

    Business website URL.

  • Name
    billing_address.name
    Type
    string
    Description

    Name of the billing area.

  • Name
    billing_address.state
    Type
    string
    Description

    State where the business is registered.

  • Name
    billing_address.city
    Type
    string
    Description

    City where the business is registered.

  • Name
    billing_address.address_street_1
    Type
    string
    Description

    Billing Address line 1.

  • Name
    billing_address.address_street_2
    Type
    string
    Description

    Billing Address line 2.

  • Name
    billing_address.zip
    Type
    string
    Description

    Business area zip code.

  • Name
    billing_address.phone
    Type
    string
    Description

    Phone number for billing area.

  • Name
    shipping_address.name
    Type
    string
    Description

    Name of the shipping area.

  • Name
    shipping_address.state
    Type
    string
    Description

    State for business shipping purposes.

  • Name
    shipping_address.city
    Type
    string
    Description

    City for business shipping purposes.

  • Name
    shipping_address.address_street_1
    Type
    string
    Description

    Shipping Address line 1.

  • Name
    shipping_address.address_street_2
    Type
    string
    Description

    Shipping Address line 2.

  • Name
    shipping_address.zip
    Type
    string
    Description

    Zip code for shipping area.

  • Name
    shipping_address.phone
    Type
    string
    Description

    Phone number for shipping area.

Request

POST
api/v2/businesses
curl --request POST \
  "https://payments.your-domain.com/api/v2/businesses" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"XYZ Business\",
    \"contact_first_name\": \"John\",
    \"contact_last_name\": \"Doe\",
    \"business_type\": \"company\",
    \"email\": \"john@xyz.com\",
    \"billing_address\": {
      \"name\": \"billing address\",
      \"state\": \"CA\",
      \"city\": \"Los Angeles\",
      \"address_street_1\": \"Address Line 1\",
      \"address_street_2\": \"Address Line 2\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    },
    \"shipping_address\": {
      \"name\": \"shipping address\",
      \"state\": \"CA\",
      \"city\": \"Los Angeles\",
      \"address_street_1\": \"Address Line 1\",
      \"address_street_2\": \"Address Line 2\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    }
  }"

Response

{
  "data": {
    "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "name": "XYZ Business",
    "website": null,
    "phone": null,
    "email": "john@xyz.com",
    "logo_url": null,
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "payouts_enabled": false,
    "business_type": "company",
    "created_at": 1683292509,
    "timezone": "America/New_York",
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipping address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "underwriting_status": {
      "bnpl": "PENDING",
      "factoring": "PENDING"
    },
  }
}
GETapi/v2/businesses/{id}

Retrieve a business

This endpoint allows you to retrieve a business by providing the business id.

Parameters

  • Name
    id
    Type
    string
    Description

    The ID of the business.

Request

GET
api/v2/businesses/{id}
curl --request GET \
  --get "https://payments.your-domain.com/api/v2/businesses/995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response

{
  "data": {
    "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "name": "XYZ Business",
    "website": null,
    "phone": null,
    "email": "john@xyz.com",
    "logo_url": null,
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "payouts_enabled": false,
    "business_type": "company",
    "created_at": 1683292509,
    "timezone": "America/New_York",
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipping address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "underwriting_status": {
      "bnpl": "PENDING",
      "factoring": "PENDING"
    },
  }
}
PUTapi/v2/businesses/{id}

Update a business

This endpoint allows you to perform an update on a business.

Parameters

  • Name
    name
    Type
    string
    Description

    Name of the business.

  • Name
    contact_first_name
    Type
    string
    Description

    First name of the contact.

  • Name
    contact_last_name
    Type
    string
    Description

    Last name of the contact.

  • Name
    business_type
    Type
    string
    Description

    Type of the business.

  • Name
    email
    Type
    string
    Description

    Email of the business.

Optional Parameters

  • Name
    phone
    Type
    string
    Description

    Business phone number.

  • Name
    billing_address.name
    Type
    string
    Description

    Name of the billing area.

  • Name
    billing_address.state
    Type
    string
    Description

    State where the business is registered.

  • Name
    billing_address.city
    Type
    string
    Description

    City where the business is registered.

  • Name
    billing_address.address_street_1
    Type
    string
    Description

    Billing Address line 1.

  • Name
    billing_address.address_street_2
    Type
    string
    Description

    Billing Address line 2.

  • Name
    billing_address.zip
    Type
    string
    Description

    Business area zip code.

  • Name
    billing_address.phone
    Type
    string
    Description

    Phone number for billing area.

  • Name
    shipping_address.name
    Type
    string
    Description

    Name of the shipping area.

  • Name
    shipping_address.state
    Type
    string
    Description

    State for business shipping purposes.

  • Name
    shipping_address.city
    Type
    string
    Description

    City for business shipping purposes.

  • Name
    shipping_address.address_street_1
    Type
    string
    Description

    Shipping Address line 1.

  • Name
    shipping_address.address_street_2
    Type
    string
    Description

    Shipping Address line 2.

  • Name
    shipping_address.zip
    Type
    string
    Description

    Zip code for shipping area.

  • Name
    shipping_address.phone
    Type
    string
    Description

    Phone number for shipping area.

Request

PUT
api/v2/businesses/{id}
curl --request PUT \
  "https://payments.your-domain.com/api/v2/businesses/995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Crater Invoice\",
    \"contact_first_name\": \"John\",
    \"contact_last_name\": \"Doe\",
    \"business_type\": \"company\",
    \"email\": \"john@example.com\",
    \"billing_address\": {
      \"name\": \"billing address\",
      \"state\": \"CA\",
      \"city\": \"Los Angeles\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    },
    \"shipping_address\": {
      \"name\": \"shipping address\",
      \"state\": \"CA\",
      \"city\": \"Los Angeles\",
      \"address_street_1\": \"Address 1\",
      \"address_street_2\": \"Address 2\",
      \"zip\": \"91504\",
      \"phone\": \"2345557788\"
    }
  }"

Response

{
  "data": {
    "id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "name": "Crater Invoice",
    "website": null,
    "phone": null,
    "email": "john@example.com",
    "logo_url": null,
    "contact_first_name": "John",
    "contact_last_name": "Doe",
    "payouts_enabled": false,
    "business_type": "company",
    "created_at": 1683292509,
    "timezone": "America/New_York",
    "billing_address": {
      "name": "billing address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "shipping_address": {
      "name": "shipping address",
      "address_street_1": "Address 1",
      "address_street_2": "Address 2",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "91504",
      "phone": "2345557788"
    },
    "underwriting_status": {
      "bnpl": "PENDING",
      "factoring": "PENDING"
    },
  }
}
GETapi/v2/businesses/{id}/settings

Get business settings

This endpoint allows you to get business settings.

Parameters

  • Name
    invoice_business_address_format
    Type
    string
    Description

    Business address format on invoice PDF.

  • Name
    invoice_shipping_address_format
    Type
    string
    Description

    Customer shipping address format on invoice PDF.

  • Name
    invoice_billing_address_format
    Type
    string
    Description

    Customer billing address format on invoice PDF.

  • Name
    estimate_business_address_format
    Type
    string
    Description

    Business address format on estimate PDF.

  • Name
    estimate_shipping_address_format
    Type
    string
    Description

    Customer shipping address format on estimate PDF.

  • Name
    estimate_billing_address_format
    Type
    string
    Description

    Customer billing address format on estimate PDF.

  • Name
    payment_business_address_format
    Type
    string
    Description

    Business address format on payment receipt PDF.

  • Name
    payment_from_customer_address_format
    Type
    string
    Description

    Customer address format on payment receipt PDF.

  • Name
    tax_per_item_enabled
    Type
    boolean
    Description

    Get tax per item enabled setting.

  • Name
    discount_per_item_enabled
    Type
    boolean
    Description

    Get discount per item enabled setting.

Request

GET
api/v2/businesses/{id}/settings
curl --request GET \
  "https://payments.your-domain.com/api/v2/businesses/995c98ce-cdd9-4ef6-b018-9c696cb07e9d/settings?settings[]=tax_per_item_enabled&settings[]=discount_per_item_enabled" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d"

Response

{
  "business_settings": {
    "tax_per_item_enabled": true,
    "discount_per_item_enabled": false
  }
}
PUTapi/v2/businesses/{id}/settings

Update business settings

This endpoint allows you to perform an update on a business settings.

Parameters

  • Name
    invoice_business_address_format
    Type
    string
    Description

    Set Business address format for invoice PDF.

  • Name
    invoice_shipping_address_format
    Type
    string
    Description

    Set Customer shipping address format for invoice PDF.

  • Name
    invoice_billing_address_format
    Type
    string
    Description

    Set Customer billing address format for invoice PDF.

  • Name
    estimate_business_address_format
    Type
    string
    Description

    Set Business address format for estimate PDF.

  • Name
    estimate_shipping_address_format
    Type
    string
    Description

    Set Customer shipping address format for estimate PDF.

  • Name
    estimate_billing_address_format
    Type
    string
    Description

    Set Customer billing address format for estimate PDF.

  • Name
    payment_business_address_format
    Type
    string
    Description

    Set Business address format for payment receipt PDF.

  • Name
    payment_from_customer_address_format
    Type
    string
    Description

    Set Customer address format for payment receipt PDF.

  • Name
    tax_per_item_enabled
    Type
    boolean
    Description

    Specify whether tax_per_item is enabled on this business?

  • Name
    discount_per_item_enabled
    Type
    boolean
    Description

    Specify whether discount_per_item is enabled on this business?

Request

POST
api/v2/businesses/{id}/settings
curl --request POST \
  "https://payments.your-domain.com/api/v2/businesses/995c98ce-cdd9-4ef6-b018-9c696cb07e9d/settings" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \,
  --header "business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"tax_per_item_enabled\": false,
    \"discount_per_item_enabled\": true
  }"

Response

{
  "business_settings": {
    "tax_per_item_enabled": false,
    "discount_per_item_enabled": true
  }
}