The ProfitWell Customers API let's you pull customer data out of ProfitWell.

There are two endpoints: one to retrieve an individual customer by his customer_id, and the other to search for customers.

IMPORTANT: The URLs MUST end in a slash, and any query parameters must go after that slash.

Authorization

For all your requests, you must provide an "Authorization" header whose value is your private API token (found in the ProfitWell app).

Retrieve a Customer by ID

URL: https://api.profitwell.com/v2/customers/<customer_id>/

Where <customer_id> is replaced with the data-provider specific customer ID. In Stripe, for example, the customer_id is something like cus_H7EURG4fhTh6oN

Returns a JSON representation of the customer

Search for Customers

This is the more useful endpoint. You can use it to iterate through all customers, ordered by their updated_on date. You can also search for customers by email here but that's probably a less useful function.

URL: https://api.profitwell.com/v2/customers/

Query Parameters:

• date_field
  • optional
  • valid values: updated_on
  • default: updated_on
• start_date:
  • optional
  • inclusive
  • Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"
  • default: None
• end_date:
  • optional
  • exclusive
  • Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"
  • default: None
• email:
  • optional
  • default: None
• page:
  • optional
  • default: 1
  • max: 100000 / per_page
• per_page:
  • optional
  • default: 250
  • max: 250
• direction
  • optional
  • valid values: asc, desc
  • default: asc

So a full URL might be:

https://api.profitwell.com/v2/customers/?date_field=updated_on&start_date=2020-05-20 12:00:00&end_date=2020-05-21 00:00:00&page=1&per_page=10&direction=asc

And again, notice how the query parameters follow a trailing slash.

If you're iterating through a company with lots of customers, and you've exhausted the maximum page number, just move the start_date of the query forward. In fact, moving the start_date forward results in faster responses than using high page numbers.

Error codes:

• 401 for either endpoint if you're unauthorized
• 404 for the "Retrieve a Customer By ID" endpoint if the customer cannot be found
• 400 for the "Search for Customers" endpoint if one of the query parameters is invalid
• 500 for either endpoint if something unexpected goes wrong on our end

Possible customer status'

• trialing
• active
• cancelled
• churned_voluntary
• churned_delinquent
• churned_trial
• no_history