# Plan

## Plan <a href="#api-plan-plan" id="api-plan-plan"></a>

Create and manage the plans that you will need to set up your customers on subscription payments.

**BASE URI**

`https://apigateway.payfirma.com/plan-service`

### Create a plan <a href="#api-plan-createaplan" id="api-plan-createaplan"></a>

Create a new plan

**HTTPS POST**

`/plan`

| **Request Arguments**           |                                                                                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <p>name</p><p>REQUIRED</p>      | The title you give to each plan, which should be unique for each plan.                                                                   |
| <p>amount</p><p>REQUIRED</p>    | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                                                    |
| <p>currency</p><p>REQUIRED</p>  | Transaction currency, in currency type, e.g. USD, CAD.                                                                                   |
| <p>frequency</p><p>REQUIRED</p> | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| number\_of\_payments            | The total number of payments within this plan.                                                                                           |
| send\_receipt                   | Sets whether receipt should be sent after transaction. Default is false.                                                                 |

| **Response Attributes**                    |                                                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>                     | Internal ID representation.                                                                                                              |
| <p>lookup\_id</p><p>string</p>             | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                         |
| <p>name</p><p>string</p>                   | The title you give to each plan, which should be unique for each plan.                                                                   |
| <p>amount</p><p>number</p>                 | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                                                    |
| <p>currency</p><p>string</p>               | Transaction currency, in currency type, e.g. USD, CAD.                                                                                   |
| <p>frequency</p><p>string</p>              | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| <p>number\_of\_payments</p><p>number</p>   | The total number of payments within this plan.                                                                                           |
| <p>send\_receipt</p><p>boolean</p>         | Sets whether receipt should be sent after transaction. Default is false.                                                                 |
| <p>total\_subscriptions</p><p>number</p>   | Total number of subscriptions under this plan.                                                                                           |
| <p>current\_subscriptions</p><p>number</p> | Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.                                                                  |

Example Request:

```
curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"name\": \"Sample Daily Plan\",
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"frequency\": \"DAILY\",
  \"number_of_payments\": 10,
  \"send_receipt\": false
}" \
"https://apigateway.payfirma.com/plan-service/plan"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}
```

### Retrieve all plans <a href="#api-plan-retrieveallplans" id="api-plan-retrieveallplans"></a>

Request the list of all plans that are active

**HTTPS GET**

`/plan{?limit,before,after,plan_name,min_amount,max_amount,frequency,min_number_of_total_subscriptions,max_number_of_total_subscriptions,min_number_of_current_subscriptions,max_number_of_current_subscriptions}`

| **URI Parameters**                          |                                                                                                                                          |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **limit**                                   | The number of transactions to be displayed within each page.                                                                             |
| **before**                                  | The begginning of the page cursor. One can use this cursor with a query parameter to get the page before this page.                      |
| **after**                                   | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page.                       |
| plan\_name                                  | The name established for the plan.                                                                                                       |
| min\_amount                                 | Filter all transactions below the given amount from the result set.                                                                      |
| max\_amount                                 | Filter all transactions above the given amount from the result set.                                                                      |
| frequency                                   | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| min\_number\_of\_total\_subscriptions       | Returns all plans with total number of subscriptions less or equal than the given minimum number.                                        |
| max\_number\_of\_total\_subscriptions       | Returns all plans with total number of subscriptions greater or equal than the given maximum number.                                     |
| min\_number\_of\_current\_subscriptions     | Returns all plans with current number of subscriptions less or equal than the given minimum number.                                      |
| **max\_number\_of\_current\_subscriptions** | Returns all plans with current number of subscriptions greater or equal than the given maximum number.                                   |

| **Response Attributes**     |                                                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| <p>entities</p><p>array</p> | The stored customer information that was associated with each transaction.                                         |
| <p>paging</p><p>object</p>  | Parameter to view multiple pages on large queries.                                                                 |
| <p>cursors</p><p>object</p> | Set the boundaries for displayed results.                                                                          |
| <p>before</p><p>string</p>  | The beginning of the page cursor. One can use this cursor with a query parameter to get the page before this page. |
| <p>after</p><p>string</p>   | The end of the page cursor. One can use this cursor with an after query parameter to get the page after this page. |

Example Request:

```
curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan?limit=100&before=%273X67XWEE%27&after=%27XWERE836%27&plan_name=%27Sample%20Daily%20Plan%27&min_amount=7.89&max_amount=799.89&frequency=frequency&min_number_of_total_subscriptions=7&max_number_of_total_subscriptions=70&min_number_of_current_subscriptions=2&max_number_of_current_subscriptions=20"
```

Example Response Body:

```
{
  'plans':[{"id":2992429,"lookup_id":"99ffb59876mnb","name":"Sample Daily Plan","amount":10.99,"currency":"CAD","frequency":"DAILY","number_of_payments":10,"send_receipt":false,"total_subscriptions":10,"current_subscriptions":2}],
  'paging': {"cursors":{"before":"51pmdq8z5rdbRWoKYrje","after":"xv9Aq54WEy3RyWEBXypK"}},
}
```

### Retrieve a plan <a href="#api-plan-retrieveaplan" id="api-plan-retrieveaplan"></a>

Query a specific plan using the plan lookup\_id

**HTTPS GET**

`/plan/{plan_lookup_id}`

| **URI Parameters** |                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------ |
| plan\_lookup\_id   | A hashed version of the plan\_id used to identify the plan in the customer & plan service. |

| **Response Attributes**                    |                                                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>                     | Internal ID representation.                                                                                                              |
| <p>lookup\_id</p><p>string</p>             | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                         |
| <p>name</p><p>string</p>                   | The title you give to each plan, which should be unique for each plan.                                                                   |
| <p>amount</p><p>number</p>                 | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                                                    |
| <p>currency</p><p>string</p>               | Transaction currency, in currency type, e.g. USD, CAD.                                                                                   |
| <p>frequency</p><p>string</p>              | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| <p>number\_of\_payments</p><p>number</p>   | The total number of payments within this plan.                                                                                           |
| <p>send\_receipt</p><p>boolean</p>         | Sets whether receipt should be sent after transaction. Default is false.                                                                 |
| <p>total\_subscriptions</p><p>number</p>   | Total number of subscriptions under this plan.                                                                                           |
| <p>current\_subscriptions</p><p>number</p> | Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.                                                                  |

Example Request:

```
curl --include \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}
```

### Update a plan <a href="#api-plan-updateaplan" id="api-plan-updateaplan"></a>

Update plan attributes using the plan lookup\_id. Active subscriptions for this plan will continue with the previous attributes and net new subscriptions will use the new attributes.

**HTTPS PUT**

`/plan/{plan_lookup_id}`

| **URI Parameters** |                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------ |
| plan\_lookup\_id   | A hashed version of the plan\_id used to identify the plan in the customer & plan service. |

| **Request Arguments**           |                                                                                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <p>name</p><p>REQUIRED</p>      | The title you give to each plan, which should be unique for each plan.                                                                   |
| <p>amount</p><p>REQUIRED</p>    | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                                                    |
| <p>currency</p><p>REQUIRED</p>  | Transaction currency, in currency type, e.g. USD, CAD.                                                                                   |
| <p>frequency</p><p>REQUIRED</p> | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| number\_of\_payments            | The total number of payments within this plan.                                                                                           |
| send\_receipt                   | Sets whether receipt should be sent after transaction. Default is false.                                                                 |

| **Response Attributes**                    |                                                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| <p>id</p><p>number</p>                     | Internal ID representation.                                                                                                              |
| <p>lookup\_id</p><p>string</p>             | A hashed identifier used to identify and access saved customers, cards, plans and subscriptions.                                         |
| <p>name</p><p>string</p>                   | The title you give to each plan, which should be unique for each plan.                                                                   |
| <p>amount</p><p>number</p>                 | Transaction amount, in dollars, e.g. 10.99 = 10 dollars and 99 cents.                                                                    |
| <p>currency</p><p>string</p>               | Transaction currency, in currency type, e.g. USD, CAD.                                                                                   |
| <p>frequency</p><p>string</p>              | The cycle of how often the card will be charged on the subscription or plan. Choices are: DAILY, WEEKLY, MOTHLY, QUARTERLY, or ANNUALLY. |
| <p>number\_of\_payments</p><p>number</p>   | The total number of payments within this plan.                                                                                           |
| <p>send\_receipt</p><p>boolean</p>         | Sets whether receipt should be sent after transaction. Default is false.                                                                 |
| <p>total\_subscriptions</p><p>number</p>   | Total number of subscriptions under this plan.                                                                                           |
| <p>current\_subscriptions</p><p>number</p> | Current number of subscriptions as ACTIVE, RETRY, SUSPENDED and PAUSED.                                                                  |

Example Request:

```
curl --include \
     --request PUT \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
     --data-binary "{
  \"name\": \"Sample Daily Plan\",
  \"amount\": 10.99,
  \"currency\": \"CAD\",
  \"frequency\": \"DAILY\",
  \"number_of_payments\": 10,
  \"send_receipt\": false
}" \
"https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"
```

Example Response Body:

```
{
  'id': 2992429,
  'lookup_id': '99ffb59876mnb',
  'name': 'Sample Daily Plan',
  'amount': 10.99,
  'currency': 'CAD',
  'frequency': 'DAILY',
  'number_of_payments': 10,
  'send_receipt': false,
  'total_subscriptions': 10,
  'current_subscriptions': 2,
}
```

### Remove a plan <a href="#api-plan-removeaplan" id="api-plan-removeaplan"></a>

Delete a plan using the plan lookup\_id. Active subscriptions for the deleted plan will continue.

**HTTPS DELETE**

`/plan`

| **URI Parameters** |                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------ |
| plan\_lookup\_id   | A hashed version of the plan\_id used to identify the plan in the customer & plan service. |

```
curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhY2Nlc3NfdG9rZW4iOiIxM2EyN2ViZS1iZTEwLTQzY2ItYjFmOC1lYjY4ZWEwOGFlNGIiLCJleHAiOjE0NTcwNTU0NjN9._KIfokRmM38MjP-q2pxB6Lk_-dcg2VnLg9QiuwksxKU" \
  "https://apigateway.payfirma.com/plan-service/plan/99ffb59876mnb"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.payfirma.com/api/plan.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.