MRR.io’s API follows REST principles. It has resource-oriented URLs and uses HTTP codes to indicate errors. It returns data as JSON, and requires data submitted to be JSON. HTTP Basic Auth is used with your API keys. All data is transferred via HTTPS.
Metrics are recalculated every few hours. You can trigger the recalculation manually at any time from within the app.
The manual data can be accessed via API as well as the app. As such, we recommend to add a few Plans, Customers and Subscription via the app and then try to access them via the API. After you can successfully fetch existing data (added manually), you can start modifying and deleting it via the API, and adding new data.
Need help? Simply reach out to support at [email protected].
Use api-key-id and api-key-secret obtained from your account settings as username and password via HTTP Basic Auth. Here’s an example:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions"
By default you get up to 10 results of page 1. Here’s how to increase it to 100 results:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?limit=100"
Getting the next page (page 2):
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?limit=100&page=2"
| Plans | https://api.mrr.io/v0.2/plans |
| Customers | https://api.mrr.io/v0.2/customers |
| Subscriptions | https://api.mrr.io/v0.2/subscriptions |
| Charges | https://api.mrr.io/v0.2/charges |
| Failed Charges | https://api.mrr.io/v0.2/failed_charges |
| Refunds | https://api.mrr.io/v0.2/refunds |
The Plan object
{
"id": 12345,
"plan_id": "pro250_monthly",
"name": "Pro 250",
"amount": 19,
"currency": "USD",
"interval": "month",
"interval_count": 1
}
List all plans
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans"
Add new plan
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans" -X POST --data @payload.json
where payload.json is a file that contains the details of the plan, e.g.
{
"plan_id": "pro250_monthly",
"name": "Pro 250",
"amount": 19,
"currency": "USD",
"interval": "month",
"interval_count": 1
}
Show a specific plan
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans/12345"
If you don’t know the ID, but know plan_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans?plan_id=pro250_monthly"
Update existing plan
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans/12345" -X PUT --data @payload.json
where payload.json is a file that contains the details of the plan, e.g.
{
"plan_id": "pro250_yearly",
"name": "Pro 250",
"amount": 190,
"currency": "USD",
"interval": "year",
"interval_count": 1
}
Delete a plan
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/plans/12345" -X DELETE
The Customer object
{
"id": 12345,
"customer_id": "cus_345678",
"name": "John Smith",
"email": "[email protected]"
}
List all customers
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customers"
Add new customer
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customers" -X POST --data @payload.json
where payload.json is a file that contains the details of the customer, e.g.
{
"customer_id": "cus_345678",
"name": "John Smith",
"email": "[email protected]"
}
Show a specific customer
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customer/12345"
If you don’t know the ID, but know customer_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customers?customer_id=cus_345678"
Update existing customer
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customers/12345" \
-X PUT --data @payload.json
where payload.json is a file that contains the details of the customer, e.g.
{
"customer_id": "cus_345678",
"name": "Johnny Smith",
"email": "[email protected]"
}
Delete a customer
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/customers/12345" -X DELETE
The Subscription object
{
"id": 12345,
"subscription_id": "sub_987654",
"customer_id": "cus_345678",
"plan_id": "pro250_monthly",
"quantity": 1,
"percent_off": 10,
"amount_off": null,
"start": 1451649600,
"end": null
}
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions"
Add new subscription
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions" \
-X POST --data @payload.json
where payload.json is a file that contains the details of the subscription, e.g.
{
"subscription_id": "sub_987654",
"customer_id": "cus_345678",
"plan_id": "pro250_monthly",
"quantity": 1,
"percent_off": 10,
"amount_off": null,
"start": 1451649600,
"end": null
}
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscription/12345"
If you don’t know the ID, but know subscription_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?subscription_id=sub_987654"
If you know customer_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?customer_id=cus_345678"
If you know plan_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?plan_id=pro250_monthly"
To limit any of the above to the latest subscription, add limit=1 to the end of the URL, like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions?subscription_id=sub_987654&limit=1"
Note: do you want to change an existing subscription (subscription upgrade/downgrade) without losing historical data? Read here!
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions/12345" -X PUT --data @payload.json
where payload.json is a file that contains the details of the subscription, e.g.
{
"subscription_id": "sub_987654",
"customer_id": "cus_345678",
"plan_id": "pro250_yearly",
"quantity": 1,
"percent_off": 10,
"amount_off": null,
"start": 1451649600,
"end": null
}
Delete a subscription
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions/12345" -X DELETE
The Charge object
{
"id": 12345,
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 19.99,
"currency": "USD"
}
List all charges
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges"
Add new charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges" -X POST --data @payload.json
where payload.json is a file that contains the details of the charge, e.g.
{
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 19.99,
"currency": "USD"
}
Show a specific charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges/12345"
If you don’t know the ID, but know customer_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges?customer_id=cus_87654"
Update existing charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges/12345" -X PUT --data @payload.json
where payload.json is a file that contains the details of the charge, e.g.
{
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 29.99,
"currency": "USD"
}
Delete a charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/charges/12345" -X DELETE
The Failed charge object
{
"id": 12345,
"customer_id": "cus_345678",
"created": "1451649600"
}
List all failed charges
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges"
Add new failed charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges" \
-X POST --data @payload.json
where payload.json is a file that contains the details of the failed charge, e.g.
{
"customer_id": "cus_345678",
"created": "1451649600"
}
Show a specific failed charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges/12345"
If you don’t know the ID, but know customer_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges?customer_id=cus_87654"
Update existing failed charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges/12345" \
-X PUT --data @payload.json
where payload.json is a file that contains the details of the failed charge, e.g.
{
"customer_id": "cus_345679",
"created": "1451649600"
}
Delete a failed charge
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/failed_charges/12345" -X DELETE
The Refund object
{
"id": 12345,
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 19.99,
"currency": "USD"
}
List all refunds
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refunds"
Add new refund
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refunds" -X POST --data @payload.json
where payload.json is a file that contains the details of the refund, e.g.
{
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 19.99,
"currency": "USD"
}
Show a specific refund
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refunds/12345"
If you don’t know the ID, but know customer_id, you can find it like so:
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refunds?customer_id=cus_87654"
Update existing refund
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refunds/12345" -X PUT --data @payload.json
where payload.json is a file that contains the details of the refund, e.g.
{
"customer_id": "cus_345678",
"created": "1451649600",
"amount": 29.99,
"currency": "USD"
}
Delete a refund
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/refund/12345" -X DELETE
When a subscription ends (e.g. a customer cancels), you should not delete the subscription, as this would result in the historical numbers affected. Instead, you should mark the subscription as cancelled by specifying the end timestamp on the subscription object.
Here are the steps involved:
end value from null to the timestamp of when the subscription was cancelled
You can add several Subscription segments with the same subscription_id and customer_id to represent changes to the subscription over time. It is important to keep the subscription_id and customer_id consistent, as this is how MRR.io determines they all belong to the same subscription.
Let’s assume Mr. Customer was previously on Basic plan, paying $10/mo. Here’s his subscription details:
{
"id": "928374"
"subscription_id": "sub_12345",
"customer_id": "mr_customer",
"plan_id": "basic",
"quantity": 1,
"percent_off": null,
"amount_off": null,
"start": 1451649600,
"end": null
}
Mr. Customer decided to upgrade to the Pro plan that costs $20/mo. Here’s how we’d represent that change:
Let's add a new segment for Mr. Customer - we’re going to set it to Pro plan ($20/mo):
curl --user {api-key-id}:{api-key-secret} \
"https://api.mrr.io/v0.2/subscriptions" \
-X POST --data @payload.json
where payload.json is:
{
"subscription_id": "sub_12345", // the same as before
"customer_id": "mr_customer", // the same as before
"plan_id": "pro", // new plan
"quantity": 1,
"percent_off": null,
"amount_off": null,
"start": 1452427200, // time when the change happened
"end": null
}
Notice the subscription_id and customer_id are consistent between both segments of the subscription, while the plan_id and start changed.
There is no limit to the number of segments you can create for each subscription.
Questions? Want to discuss your specific case? Email support at [email protected]