ProfitWell API v2

https://profitwellapiv2.docs.apiary.io
Admin
The ProfitWell API v2 allows users to programmatically add and retrieve data from their ProfitWell...
Tokens:11,668
Snippets:39
Trust Score:9.9
Update:11 months ago
Show doc for...
Tokens:
Raw
### GET /company/settings

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve your company's ProfitWell account settings, including company ID, name, timezone, and currency.

```APIDOC
## GET /company/settings

### Description
Get your company's ProfitWell account settings. These include your company ID, name, timezone, and the currency in which your metrics are displayed.

### Method
GET

### Endpoint
/company/settings

### Parameters
No parameters are required for this endpoint.

### Request Example
```
GET /company/settings
```

### Response
#### Success Response (200)
- **company_id** (string) - The unique identifier for the company.
- **name** (string) - The name of the company.
- **timezone** (string) - The timezone configured for the company.
- **currency** (string) - The currency used for displaying metrics.

#### Response Example
```json
{
  "company_id": "comp_abc",
  "name": "Example Corp",
  "timezone": "America/New_York",
  "currency": "USD"
}
```
```

--------------------------------

### GET /websites/profitwellapiv2_apiary_io/metrics/monthly

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve all monthly financial metrics for your company. Optionally scope to an individual metric and/or plan. The response contains an object whose keys are the metrics trend names, and whose values are an array of records containing the `date` and `value`.

```APIDOC
## GET /websites/profitwellapiv2_apiary_io/metrics/monthly

### Description
Retrieve all monthly financial metrics for your company. Optionally scope to an individual metric and/or plan. The response contains an object whose keys are the metrics trend names, and whose values are an array of records containing the `date` and `value`.

### Method
GET

### Endpoint
/websites/profitwellapiv2_apiary_io/metrics/monthly

### Parameters
#### Query Parameters
- **metric** (string) - Optional - The specific metric to retrieve. If not provided, all available metrics are returned.
- **plan** (string) - Optional - The specific plan to scope the metrics to. If not provided, metrics for all plans are returned.

### Request Example
```json
{
  "query": {
    "metric": "recurring_revenue",
    "plan": "basic"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - An object where keys are metric trend names and values are arrays of records.
  - **date** (string) - The date of the metric in `YYYY-MM` format.
  - **value** (number) - The value of the metric for that month. Values are in the company's currency for amounts or percentages for rates.

#### Response Example
```json
{
  "data": {
    "recurring_revenue": [
      {
        "date": "2023-01",
        "value": 10000.50
      },
      {
        "date": "2023-02",
        "value": 12000.75
      }
    ],
    "active_customers": [
      {
        "date": "2023-01",
        "value": 100
      },
      {
        "date": "2023-02",
        "value": 110
      }
    ]
  }
}
```
```

--------------------------------

### GET /plans

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve your company's active plan IDs, sorted by MRR. Will only return plan IDs for which there are currently active customers, and will return at most 150.

```APIDOC
## GET /plans

### Description
Retrieve your company's active plan IDs, sorted by MRR. Will only return plan IDs for which there are currently active customers, and will return at most 150.

### Method
GET

### Endpoint
/plans

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Optionally return up to this many plan IDs (max and default are 150).

### Response
#### Success Response (200)
- **plan_id** (string) - The ID of the plan.

#### Response Example
```json
[
  "plan_id_1",
  "plan_id_2"
]
```
```

--------------------------------

### GET /daily_metrics

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve financial metrics broken down by day for either the current month or the last. Optionally scope to an individual metric and/or plan.

```APIDOC
## GET /daily_metrics

### Description
Retrieve financial metrics broken down by day for either the current month or the last. Optionally scope to an individual metric and/or plan.
In the response, the `data` key contains an object whose keys are the metrics trend names, and whose values are an array of records containing the `date` and `value` of the given trend for each day. The dates are all in the format `YYYY-MM-DD` (e.g. 2018-05-15). The values are all numbers, with precision up to two places after the decimal point. When relating to amounts (e.g. `recurring_revenue`), the values are in the currency listed in your ProfitWell account's settings.
Some metrics are available only when you are retrieving data for ALL plans. See the `Segment by Individual Plan` column in the table below to determine which trends can be segmented by plan.

### Method
GET

### Endpoint
/daily_metrics

### Parameters
#### Query Parameters
- **month** (string) - Required - Return daily metrics trends for this month. Can only be the current or previous month. Format should be YYYY-MM (e.g. 2018-09).
- **plan_id** (string) - Optional - Optionally only return the metrics for this plan_id.
- **metrics** (string) - Optional - An optional, comma-separated list of metrics trends to return (the default is to return all metrics).

### Request Example
```json
{
  "month": "2018-09",
  "metrics": "recurring_revenue"
}
```

### Response
#### Success Response (200)
- **data** (object) - An object where keys are metric trend names and values are arrays of daily records.
    - **date** (string) - The date of the metric.
    - **value** (number) - The value of the metric for that day.

#### Response Example
```json
{
  "data": {
    "recurring_revenue": [
      {
        "date": "2018-09-01",
        "value": 15000.50
      }
    ]
  }
}
```

#### Error Codes
**400** : If your request contains an invalid month for the `month` parameter, invalid metrics trend names for the `metrics` parameter, or if it contains unknown query paramters, we will return a response with a 400 status code.
```

--------------------------------

### Get Subscription History for User

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieves the history of subscription updates made to a specific user.

```APIDOC
## GET /users/{user_id_OR_user_alias}/subscriptions/history

### Description
Get the history of subscription updates you've made to a user.

### Method
GET

### Endpoint
/users/{user_id_OR_user_alias}/subscriptions/history

### Parameters
#### Path Parameters
- **user_id_OR_user_alias** (string) - Required - Either the `user_id` or the `user_alias` of the user.

### Response
#### Success Response (200 OK)
- **subscriptions** (array) - An array of subscription history objects for the user.
  - **plan_id** (string) - The ID of the plan.
  - **plan_interval** (string) - The billing cycle of the plan.
  - **value** (number) - The value of the plan in cents.
  - **status** (string) - The status of the subscription.
  - **effective_date** (number) - The UNIX timestamp when the change took effect.
  - **created_at** (number) - The UNIX timestamp when the subscription record was created.
```

--------------------------------

### GET /customers/{customer_id}/traits

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve a specific customer's traits. Returns traits in the format {category: trait, ...}.

```APIDOC
## GET /customers/{customer_id}/traits

### Description
Returns a customer's traits in the form of `{category: trait, ...}`.

### Method
GET

### Endpoint
/customers/{customer_id}/traits

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The unique identifier for the customer.

### Request Example
```
GET /customers/cust_123/traits
```

### Response
#### Success Response (200)
- **traits** (object) - An object where keys are trait categories and values are the corresponding traits.

#### Response Example
```json
{
  "super_power": "gadgets",
  "job_category": "developer"
}
```
```

--------------------------------

### GET /customers/unsubscribed

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieve customers that have unsubscribed from Retain Term Optimization or Reactivation emails. Supports filtering by date range and pagination.

```APIDOC
## GET /customers/unsubscribed

### Description
Retrieve customers that unsubscribed from Retain Term Optimization or Reactivation emails. Supports date range filtering and pagination.

### Method
GET

### Endpoint
/customers/unsubscribed

### Parameters
#### Query Parameters
- **intervention_type** (string) - Required - Must be either "term_optimization" or "reactivation"
- **start_date** (string/timestamp) - Optional - Get customers who unsubscribed on `start_date` or later. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"
- **end_date** (string/timestamp) - Optional - Get customers who unsubscribed on `end_date` or before. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z"
- **page** (integer) - Optional - The page number. Max value: 100000 / `per_page`. Default value: 1.
- **per_page** (integer) - Optional - The number of customers per page. Max value: 250. Default value: 250.

### Request Example
```
GET /customers/unsubscribed?intervention_type=term_optimization&start_date=2023-01-01T00:00:00Z&page=1&per_page=50
```

### Response
#### Success Response (200)
- **customers** (array) - A list of customer objects that match the criteria.
  - **customer_id** (string) - The unique identifier for the customer.
  - **email** (string) - The email address of the customer.
  - **unsubscribed_at** (string) - The timestamp when the customer unsubscribed.

#### Response Example
```json
{
  "customers": [
    {
      "customer_id": "cust_123",
      "email": "test@example.com",
      "unsubscribed_at": "2023-05-15T10:30:00Z"
    }
  ]
}
```

### Error Handling
- **400** : If one of the url or query parameters is invalid.
```

--------------------------------

### Create New Plan

Source: https://profitwellapiv2.docs.apiary.io/index

Creates a new, manually-added plan.

```APIDOC
## POST /plans

### Description
Create a new, manually-added plan. You may create a new plan using this endpoint. Alternatively, if you create a manually-added subscription and place that subscription on a plan that has never been referenced before, that plan will automatically be created. If you try to create a plan that already exists, this endpoint will return an error.

### Method
POST

### Endpoint
/plans

### Parameters
#### Request Body
- **id** (string) - Required - The ID of the new plan. This ID may not conflict with any other manually-added plan or plan coming from your connected data provider (e.g. Stripe).
- **name** (string) - Required - The name of the plan.

### Request Example
```json
{
  "id": "new_custom_plan",
  "name": "New Custom Plan"
}
```

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the created plan.
- **name** (string) - The name of the created plan.
```

--------------------------------

### POST /subscriptions

Source: https://profitwellapiv2.docs.apiary.io/index

Creates a new subscription for a user. You can either create a first-time subscription for a new user or add an additional subscription to an existing user.

```APIDOC
## POST /subscriptions

### Description
Creates a new subscription for a user. This can be the user's first subscription or an additional one for an existing user.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **user_id** (string, optional) - The user ID. Omit if creating the user's first subscription. Automatically generated by ProfitWell for new users. Include only if adding a subscription to an existing user.
- **user_alias** (string, optional) - Your own identifier for the user. Useful for subsequent requests without needing to store ProfitWell's user_id. Required if creating a second subscription for a user and user_id is not provided.
- **subscription_alias** (string, optional) - Your own identifier for the subscription. Must be unique across all users. Max 36 characters. Useful for subsequent requests without needing to store ProfitWell's subscription_id. Required if updating a subscription and subscription_id is not provided.
- **email** (string) - The email address or display name for the user. This field does not uniquely identify a user.
- **plan_id** (string) - The ID of the plan the user is on.
- **plan_interval** (string) - The billing cycle for the plan. Accepted values: "month", "year".
- **plan_currency** (string, optional) - The currency code (ISO 4217) for the plan. Defaults to "usd".
- **status** (string, optional) - The status of the subscription. Accepted values for new subscriptions: "active", "trialing". Defaults to "active". Subscriptions with status "trialing" must have a value of 0.
- **value** (number) - The amount billed per period, in cents. For annual plans, keep the value unmodified (e.g., $120.00/year is 12000).
- **effective_date** (number) - The subscription start date in UNIX timestamp format.
- **data_provider_user_id** (string, optional) - User ID from an external data provider (e.g., Stripe). Not currently used by the API.

### Request Example
```json
{
  "email": "user@example.com",
  "plan_id": "plan_123",
  "plan_interval": "month",
  "value": 5000,
  "effective_date": 1678886400
}
```

### Response
#### Success Response (201 Created)
- **subscription_id** (string) - The unique identifier for the created subscription.
- **user_id** (string) - The unique identifier for the user associated with the subscription.

#### Response Example
```json
{
  "subscription_id": "sub_abc123",
  "user_id": "user_xyz789"
}
```
```

--------------------------------

### List All Plans

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieves a list of all manually-added plans.

```APIDOC
## GET /plans

### Description
List all manually-added plans.

### Method
GET

### Endpoint
/plans

### Response
#### Success Response (200 OK)
- **plans** (array) - An array of plan objects.
  - **id** (string) - The ID of the plan.
  - **name** (string) - The name of the plan.
```

--------------------------------

### Retrieve a Plan

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieves a single manually-added plan by its ID.

```APIDOC
## GET /plans/{id}

### Description
Retrieve a single manually-added plan by ID.

### Method
GET

### Endpoint
/plans/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the manually-added plan you wish to retrieve.

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the plan.
- **name** (string) - The name of the plan.
```

--------------------------------

### POST /dotjs/v1/customer/event/

Source: https://profitwellapiv2.docs.apiary.io/index

Creates a customer event, typically a login event, for a given user. This is useful when Profitwell.js or Paddle.js cannot be integrated directly.

```APIDOC
## POST /dotjs/v1/customer/event/

### Description
Create a customer event when a customer logs into your system. If it is not possible to integrate the profitwell.js or Paddle.js scripts in your system, you can send customer login events using this endpoint.

> **Note:** This endpoint requires your **public** token to be passed in the `Authorization` header. This token can be found in the Account Settings -> Integrations tab of your Profitwell account.

### Method
POST

### Endpoint
https://api.profitwell-events.com/dotjs/v1/customer/event/

#### Query Parameters
None

#### Headers
- **Authorization** (string) - Required - Your public Profitwell token.
- **Content-Type** (string) - Required - Must be `application/json`.

#### Request Body
- **user_id** (string) - Required - The unique identifier for the customer.

### Request Example
```json
{
    "user_id": "cus_1234"
}
```

### Response
#### Success Response (204)
No Content. Indicates the event was successfully recorded.

#### Response Example
(No body returned on success)

#### Error Codes
- **400** : If the body's JSON is invalidly formatted or the customer cannot be found. The `error` field in the response will contain the reason.
- **415** : If the content type is unsupported. This endpoint supports `application/json` content.
```

--------------------------------

### Create Subscription

Source: https://profitwellapiv2.docs.apiary.io/index

This endpoint allows you to create a new subscription in your ProfitWell account. You can add a subscription for a new user or for an existing user with another subscription. It's crucial to store the returned `subscription_alias` or `subscription_id` for future updates or churn operations.

```APIDOC
## POST /customers/subscriptions

### Description
Create a new subscription. Can be for a new user, or a user who already has another subscription. It is important that you store either the **subscription_alias** that you use to create this subscription, or the **subscription_id** that ProfitWell returns in the response, so that you can update/churn this subscription at a later date.
IMPORTANT: If you are creating multiple subscriptions for the same user, it is important that you wait for a response from the API after creating the first subscription before creating subsequent subscriptions.

### Method
POST

### Endpoint
/customers/subscriptions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **subscription_alias** (string) - Required - An alias for the subscription.
- **plan_alias** (string) - Required - The alias of the plan associated with this subscription.
- **customer_alias** (string) - Required - An alias for the customer.
- **subscribed_at** (datetime) - Optional - The date and time the subscription was made.
- **period_start** (datetime) - Optional - The start date of the current billing period.
- **period_end** (datetime) - Optional - The end date of the current billing period.
- **price_per_period** (decimal) - Optional - The price of the subscription per billing period.
- **currency** (string) - Optional - The currency of the subscription price.

### Request Example
```json
{
  "subscription_alias": "sub_12345",
  "plan_alias": "basic_plan",
  "customer_alias": "cust_abcde",
  "subscribed_at": "2023-01-15T10:00:00Z",
  "price_per_period": 29.99,
  "currency": "USD"
}
```

### Response
#### Success Response (200 or 201)
- **subscription_id** (string) - The unique identifier for the created subscription.
- **subscription_alias** (string) - The alias of the created subscription.
- **customer_id** (string) - The unique identifier for the customer.
- **customer_alias** (string) - The alias of the customer.
- **plan_id** (string) - The unique identifier for the plan.
- **plan_alias** (string) - The alias of the plan.

#### Response Example (201)
```json
{
  "subscription_id": "sub_xyz789",
  "subscription_alias": "sub_12345",
  "customer_id": "cust_fghij",
  "customer_alias": "cust_abcde",
  "plan_id": "plan_klmno",
  "plan_alias": "basic_plan"
}
```
```

--------------------------------

### Search Customers

Source: https://profitwellapiv2.docs.apiary.io/index

Search for customers by email or retrieve customers updated since a specific date. Supports pagination and ordering.

```APIDOC
## GET /customers

### Description
This endpoint allows searching for customers by their email address or retrieving a list of customers updated since a specified date. It supports filtering by date range, pagination, and custom ordering.

### Method
GET

### Endpoint
/customers

#### Query Parameters
- **start_date** (string/timestamp) - Optional - Get customers updated on or after this date. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z".
- **end_date** (string/timestamp) - Optional - Get customers updated before this date. Many formats acceptable, including Unix timestamps and strings like "2020-05-20T18:45:22Z".
- **email** (string) - Optional - The customer email address to search for.
- **page** (integer) - Optional - The page number for pagination. Max value: 100000 / `per_page`. Default value: 1.
- **per_page** (integer) - Optional - The number of customers to return per page. Max value: 250. Default value: 250.
- **direction** (string) - Optional - Order the data by either ascending or descending. Valid values: "asc" or "desc". Default value: "asc".

### Response
#### Success Response (200)
- **customers** (array) - A list of customer objects.
  - **customer_id** (string) - The unique identifier for the customer.
  - **email** (string) - The email address of the customer.
  - **updated_at** (string) - The timestamp when the customer was last updated.

#### Response Example
{
  "customers": [
    {
      "customer_id": "cust_123",
      "email": "test@example.com",
      "updated_at": "2023-10-27T10:00:00Z"
    }
  ]
}

#### Error Codes
**400** : If one of the query parameters is invalid.
```

--------------------------------

### Upgrade/Downgrade Subscription

Source: https://profitwellapiv2.docs.apiary.io/index

Allows for upgrading or downgrading an existing subscription by updating its details.

```APIDOC
## PUT /subscriptions/{subscription_id}

### Description
Upgrade or downgrade an existing subscription. You must provide either the `subscription_id` or `subscription_alias` to identify the subscription.

### Method
PUT

### Endpoint
/subscriptions/{subscription_id}

### Parameters
#### Path Parameters
- **subscription_id** (string) - The unique identifier of the subscription to update.

#### Query Parameters
- **subscription_alias** (string) - Your own identifier for the subscription. Use this if you do not have the `subscription_id`.

#### Request Body
- **plan_id** (string, optional) - The new ID of the plan.
- **plan_interval** (string, optional) - The new billing cycle for the plan. Accepted values: "month", "year".
- **plan_currency** (string, optional) - The new currency code (ISO 4217) for the plan.
- **status** (string, optional) - The new status of the subscription. Accepted values: "active", "trialing", "churned_voluntary", "churned_delinquent".
- **value** (number, optional) - The new amount billed per period, in cents.
- **effective_date** (number, optional) - The new subscription start date in UNIX timestamp format.

### Request Example
```json
{
  "plan_id": "plan_456",
  "value": 7500
}
```

### Response
#### Success Response (200 OK)
- **subscription_id** (string) - The unique identifier for the updated subscription.
- **user_id** (string) - The unique identifier for the user associated with the subscription.

#### Response Example
```json
{
  "subscription_id": "sub_abc123",
  "user_id": "user_xyz789"
}
```
```

--------------------------------

### POST /customers/traits

Source: https://profitwellapiv2.docs.apiary.io/index

Add traits to customers by email address. Applies the specified trait to all customers with the given email.

```APIDOC
## POST /customers/traits

### Description
Add traits by email address, which will apply the trait to all customers with the specified email. This endpoint is useful for bulk trait updates based on email.

### Method
POST

### Endpoint
/customers/traits

### Parameters
#### Request Body
- **email** (string) - Required - The email address of the customer(s) to update.
- **category** (string) - Required - The category of the trait (e.g., "super power").
- **trait** (string) - Required - The specific trait value (e.g., "gadgets").

### Request Example
```json
{
  "email": "bruce@waynecorp.com",
  "category": "super power",
  "trait": "gadgets"
}
```

### Response
#### Success Response (204)
No content is returned upon successful creation or update.

### Error Handling
- **400** : Invalid values for email, category, or trait, or issues with reserved category names.
```

--------------------------------

### Create Customer Event (API Request)

Source: https://profitwellapiv2.docs.apiary.io/index

This snippet demonstrates how to make a POST request to the Profitwell API to create a customer event, typically for user logins. It requires an 'Authorization' header with your public token and a JSON 'Content-Type'. The request body must include the 'user_id' of the customer.

```http
POST https://api.profitwell-events.com/dotjs/v1/customer/event/

Headers:
Authorization: 0be1442a82158361c77f851457af6625
Content-Type: application/json

Body:
{
    "user_id": "cus_1234"
}
```

--------------------------------

### API Status

Source: https://profitwellapiv2.docs.apiary.io/index

This endpoint checks the operational status of the ProfitWell API and verifies your authentication. It returns a 200 OK status if the API is running and your authentication is valid, otherwise a 401 Unauthorized response is returned.

```APIDOC
## GET /status

### Description
Returns a status code of 200 if the API is operational and if you've properly authenticated. If you haven't authenticated properly, the endpoint returns a status code of 401.

### Method
GET

### Endpoint
/status

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - Indicates the API is operational.

#### Error Response (401)
- **error** (string) - Indicates unauthorized access.

#### Response Example (200)
{
  "status": "operational"
}
```

--------------------------------

### Update a Plan

Source: https://profitwellapiv2.docs.apiary.io/index

Updates the name of an existing manually-added plan.

```APIDOC
## PUT /plans/{id}

### Description
Update the name of an existing manually-added plan.

### Method
PUT

### Endpoint
/plans/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the manually-added plan you wish to update.

#### Request Body
- **name** (string) - Required - The new name of the plan.

### Request Example
```json
{
  "name": "Updated Plan Name"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The ID of the updated plan.
- **name** (string) - The new name of the plan.
```

--------------------------------

### Retrieve Customer by ID

Source: https://profitwellapiv2.docs.apiary.io/index

Retrieves an individual customer's data using their customer ID.

```APIDOC
## GET /customers/{customer_id}

### Description
Retrieve a Customer by ID.

### Method
GET

### Endpoint
/customers/{customer_id}

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The data-provider specific customer ID.

### Response
#### Success Response (200 OK)
- **customer_id** (string) - The customer's ID.
- **email** (string) - The customer's email address.
- **name** (string) - The customer's name.
- **created_at** (number) - The UNIX timestamp when the customer was created.
- **subscriptions** (array) - An array of the customer's subscription objects.
```

--------------------------------

### POST /customers/{customer_id}/traits

Source: https://profitwellapiv2.docs.apiary.io/index

Create or update a trait for a specific customer. Traits are case-insensitive and stored in lowercase.

```APIDOC
## POST /customers/{customer_id}/traits

### Description
Create or update a trait attached to a particular customer by customer ID. Each customer can only have one trait per category. If a subsequent request for the same customer comes with a different trait for the same category, the trait will be updated.

### Method
POST

### Endpoint
/customers/{customer_id}/traits

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The unique identifier for the customer.

#### Request Body
- **category** (string) - Required - The category of the trait (e.g., "super power").
- **trait** (string) - Required - The specific trait value (e.g., "gadgets").

### Request Example
```json
{
  "category": "super power",
  "trait": "gadgets"
}
```

### Response
#### Success Response (204)
No content is returned upon successful creation or update.

### Error Handling
- **400** : Invalid values for category or trait, adding a duplicate trait, removing a non-existent trait, or using reserved category names.
```

--------------------------------

### Update User

Source: https://profitwellapiv2.docs.apiary.io/index

Updates a user's email address or other display text used on the Customers tab.

```APIDOC
## PUT /users/{user_id_OR_user_alias}

### Description
Update a user's email address. This field can also be used to store other display text like a name.

### Method
PUT

### Endpoint
/users/{user_id_OR_user_alias}

### Parameters
#### Path Parameters
- **user_id_OR_user_alias** (string) - Required - Either the `user_id` or the `user_alias` of the user.

#### Request Body
- **email** (string) - Required - The new email address or display text for the user.

### Request Example
```json
{
  "email": "new.display.text@example.com"
}
```

### Response
#### Success Response (204 No Content)
This endpoint returns no content on success.
```

--------------------------------

### Update Subscription

Source: https://profitwellapiv2.docs.apiary.io/index

Updates an existing subscription by changing its plan, billing cycle, value, status, or effective date.

```APIDOC
## POST /subscriptions/{subscription_id_OR_subscription_alias}

### Description
Updates an existing subscription. This endpoint is used for various subscription modifications such as plan changes, seat adjustments, and value updates.

### Method
POST

### Endpoint
/subscriptions/{subscription_id_OR_subscription_alias}

### Parameters
#### Path Parameters
- **subscription_id_OR_subscription_alias** (string) - Required - Either the `subscription_id` or the `subscription_alias` of the subscription to update.

#### Request Body
- **plan_id** (string) - Required - The ID of the plan that the user is switching to. If the user has not switched plans, but has added or subtracted seats on their current plan, you should use the same **plan_id** as before.
- **plan_interval** (string) - Required - The billing cycle for this plan. The two options are "month" and "year".
- **value** (number) - Required - The new amount that you bill your user, per billing period, in cents. Keep the value of annual plans unmodified, meaning a $120.00 / year plan should have a value of 12000. Note: This should always be the full value of the plan, even if the user changes plans mid-billing cycle and is charged/credited a prorated amount.
- **status** (string) - Optional - The status of the subscription. Currently, the only valid status when upgrading/downgrading a subscription is "active". Down the line, we would like to add more statuses. (Note that the API may return statuses other than "active" when retrieving a customer's subscription history, such as "trialing", "churned_voluntary" and "churned_delinquent".)
- **effective_date** (number) - Required - The date that this update takes effect, in UNIX timestamp format. (E.g. For 2018-01-1 00:00:00, the value would be 1514764800).

### Request Example
```json
{
  "plan_id": "premium_plan",
  "plan_interval": "month",
  "value": 5000,
  "status": "active",
  "effective_date": 1678886400
}
```

### Response
#### Success Response (200 OK)
This endpoint returns no specific body on success.
```

--------------------------------

### Add Trait to Customer by Email - JSON

Source: https://profitwellapiv2.docs.apiary.io/index

Adds or updates a trait for a customer identified by their email address. This method allows bulk updates for customers sharing the same email. Ensure the email exists in the system and the trait category/value are valid to avoid a 400 error.

```json
{
    "email": "bruce@waynecorp.com",
    "category": "super power",
    "trait": "gadgets"
}
```

--------------------------------

### Churn Subscription

Source: https://profitwellapiv2.docs.apiary.io/index

Churns a subscription, marking it as churned on a specified date and with a specified churn type.

```APIDOC
## POST /subscriptions/{subscription_id_OR_subscription_alias}/churn

### Description
Churns a subscription. This request's fields are query parameters in the URL. There is no body to this request.

### Method
POST

### Endpoint
/subscriptions/{subscription_id_OR_subscription_alias}/churn

### Parameters
#### Path Parameters
- **subscription_id_OR_subscription_alias** (string) - Required - Either the `subscription_id` or the `subscription_alias` of the subscription.

#### Query Parameters
- **effective_date** (number) - Required - UNIX timestamp of when the subscription churns.
- **churn_type** (string) - Optional - Acceptable values are `voluntary` or `delinquent`. Default is `voluntary`.

### Response
#### Success Response (200 OK)
This endpoint returns no specific body on success.
```

--------------------------------

### GDPR Anonymize Customer by Email

Source: https://profitwellapiv2.docs.apiary.io/index

Anonymizes a customer's data based on their email address, assisting with GDPR compliance.

```APIDOC
## POST /customers/anonymize

### Description
This endpoint anonymizes a customer's data based on their email address. This action is irreversible and is crucial for compliance with data privacy regulations such as GDPR. Note that if a customer has already been anonymized, it is not possible to distinguish between a missing customer and one that has already been processed.

### Method
POST

### Endpoint
/customers/anonymize

#### Query Parameters
- **email** (string) - Required - The customer's email address.

### Response
#### Success Response (204)
No content is returned upon successful anonymization.

#### Error Codes
**404** : If the customer cannot be found, or the customer has already been anonymized.
```

--------------------------------

### GDPR Anonymize Customer by ID

Source: https://profitwellapiv2.docs.apiary.io/index

Anonymizes a customer's data based on their unique customer ID, fulfilling GDPR requirements.

```APIDOC
## POST /customers/{customer_id}/anonymize

### Description
This endpoint anonymizes a specific customer's data using their unique `customer_id`. This action is irreversible and is used to comply with data privacy regulations like GDPR.

### Method
POST

### Endpoint
/customers/{customer_id}/anonymize

#### Path Parameters
- **customer_id** (string) - Required - The data-provider specific customer ID.

### Response
#### Success Response (204)
No content is returned upon successful anonymization.

#### Error Codes
**400** : If the customer has already been anonymized.
**404** : If the customer cannot be found.
```

--------------------------------

### Delete User

Source: https://profitwellapiv2.docs.apiary.io/index

Completely deletes a user and all associated subscription history.

```APIDOC
## DELETE /users/{user_id_OR_user_alias}

### Description
Completely delete a user and their subscription history.

### Method
DELETE

### Endpoint
/users/{user_id_OR_user_alias}

### Parameters
#### Path Parameters
- **user_id_OR_user_alias** (string) - Required - Either the `user_id` or the `user_alias` of the user.

### Response
#### Success Response (204 No Content)
This endpoint returns no content on success.
```

--------------------------------

### Un-churn Subscription

Source: https://profitwellapiv2.docs.apiary.io/index

Removes the churn event associated with a subscription, effectively restoring it.

```APIDOC
## POST /subscriptions/{subscription_id_OR_subscription_alias}/un-churn

### Description
Removes the churn event associated with a subscription. This rewrites history for the subscription, making it appear as though the subscription never churned to begin with. You may do this for a subscription that has already churned, or that is set to churn in the future.

### Method
POST

### Endpoint
/subscriptions/{subscription_id_OR_subscription_alias}/un-churn

### Parameters
#### Path Parameters
- **subscription_id_OR_subscription_alias** (string) - Required - Either the `subscription_id` or the `subscription_alias` of the subscription you'd like to un-churn.

### Response
#### Success Response (204 No Content)
This endpoint returns no content on success.
```

--------------------------------

### DELETE /categories/{category_name}

Source: https://profitwellapiv2.docs.apiary.io/index

Remove a category and all associated traits from every customer. This action is irreversible.

```APIDOC
## DELETE /categories/{category_name}

### Description
Removing a category will remove it from every customer that has a trait for the specified category. This action is irreversible. Any subsequent request that contains the category will create a new category from scratch.

### Method
DELETE

### Endpoint
/categories/{category_name}

### Parameters
#### Path Parameters
- **category_name** (string) - Required - The name of the category to remove.

### Request Example
```
DELETE /categories/super_power
```

### Response
#### Success Response (204)
No content is returned upon successful removal.
```

--------------------------------

### POST /customers/stop_retain

Source: https://profitwellapiv2.docs.apiary.io/index

Stop any possible action Retain could be taking over a given customer. This includes: sending emails to the customer, retrying with the same payment method, sending in app notifications or SMS, if applicable.

```APIDOC
## POST /customers/stop_retain

### Description
Stop any possible action Retain could be taking over a given customer. This includes: sending emails to the customer, retrying with the same payment method, sending in app notifications or SMS, if applicable.

### Method
POST

### Endpoint
/customers/stop_retain

### Parameters
#### Request Body
- **customer_id** (string) - Required - The customer ID.
- **intervention_types** (list of string) - Required - A comma-separated list of the interventions you want to stop for the given customer. The possible values are `retain`, `term_optimization` and `reactivation`.
- **forever** (boolean) - Optional - Indicates whether we have to **exclude** the user from the given interventions or not. By default, the value is `False`.

### Request Example
```json
{
  "customer_id": "cus_123abc",
  "intervention_types": ["retain", "reactivation"],
  "forever": false
}
```

### Response
#### Success Response (204)
No Content

#### Error Codes
**400** : If there isn't any open payment for the given customer, we will return a response with a 400 status code.
```

--------------------------------

### DELETE /customers/{customer_id}

Source: https://profitwellapiv2.docs.apiary.io/index

Exclude user's data from the calculation of all metrics.

```APIDOC
## DELETE /customers/{customer_id}

### Description
Exclude user's data from the calculation of all metrics.

### Method
DELETE

### Endpoint
/customers/{customer_id}

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The `id` of the customer to exclude.

### Response
#### Success Response (204)
No Content
```

--------------------------------

### DELETE /customers/{customer_id}/traits

Source: https://profitwellapiv2.docs.apiary.io/index

Remove a trait from a specific customer.

```APIDOC
## DELETE /customers/{customer_id}/traits

### Description
Removes a trait associated with a specific customer. This action targets a particular category and trait combination for a given customer.

### Method
DELETE

### Endpoint
/customers/{customer_id}/traits

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The unique identifier for the customer.

#### Query Parameters
- **category** (string) - Required - The category of the trait to remove.
- **trait** (string) - Required - The specific trait value to remove.

### Request Example
```
DELETE /customers/cust_123/traits?category=super_power&trait=gadgets
```

### Response
#### Success Response (204)
No content is returned upon successful removal.
```
Tokens:
Raw