Recurso

https://docs.recurso.dev
Admin
Recurso is an open-source billing engine that manages the full commercial lifecycle including...
Tokens:1,470,271
Snippets:9,027
Trust Score:4.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Go example

Source: https://docs.recurso.dev/api-reference/analytics/dunning-recovered

Go example using net/http to GET the endpoint. Replace <token> with your API key.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/analytics/dunning/recovered"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Go example for listing entities

Source: https://docs.recurso.dev/api-reference/entities/list

Go example using net/http to GET /v1/entities. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/entities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Go example to get an invoice

Source: https://docs.recurso.dev/api-reference/invoices/get

Go example using net/http to fetch an invoice. Replace {id} and <token> as needed.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/invoices/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### OAuth start with Go

Source: https://docs.recurso.dev/api-reference/auth/oauth-start

Go example using net/http to call the OAuth start endpoint with an Authorization header.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/oauth/{provider}/start"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Go example for getting a Compare run

Source: https://docs.recurso.dev/api-reference/import/get-compare-report

Uses net/http to send a GET request with an Authorization header. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/import/compare-reports/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Go example to get a coupon

Source: https://docs.recurso.dev/api-reference/coupons/get

Uses net/http to send a GET request with the Authorization header and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/coupons/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Install from Source

Source: https://docs.recurso.dev/quickstart

Clone the repository, install Go dependencies, set up the environment, and start the server from source. Migrations run automatically at boot.

```bash
# Clone the repository
git clone https://github.com/recurso-dev/recurso.git
cd recurso

# Install dependencies
go mod download

# Set up environment
cp .env.example .env

# Start the server — migrations run automatically at boot
make run

```

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

### OAuth start with cURL

Source: https://docs.recurso.dev/api-reference/auth/oauth-start

cURL example for the OAuth start endpoint. Uses GET with an Authorization header containing an API key.

```bash
curl --request GET \
  --url https://billing.example.com/auth/oauth/{provider}/start \
  --header 'Authorization: <api-key>'

```

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

### Start a card update with Go

Source: https://docs.recurso.dev/api-reference/portal/payment-method-setup-intent

Go example using net/http to POST to the setup-intent endpoint with the portal session cookie.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/portal/api/payment-method/setup-intent"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("cookie", "portal_session=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### List accounting connections with GET /v1/accounting/connections

Source: https://docs.recurso.dev/api-reference/accounting/connections

List accounting connections using the GET /v1/accounting/connections endpoint. Each example sends an authenticated GET request with a Bearer token and prints the response body. The cURL example uses the --request GET flag and the --url option.

```bash
curl --request GET \
  --url https://billing.example.com/v1/accounting/connections \
  --header 'Authorization: Bearer <token>'
```

```python
import requests

url = "https://billing.example.com/v1/accounting/connections"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```javascript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/accounting/connections', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/accounting/connections",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/accounting/connections"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```java
HttpResponse<String> response = Unirest.get("https://billing.example.com/v1/accounting/connections")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/accounting/connections")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

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

### Go: Start demo sandbox session

Source: https://docs.recurso.dev/api-reference/auth/demo

Go example using net/http to POST to the demo endpoint. Requires an API key in the Authorization header. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/auth/demo"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Example response for GET /v1/settings/tax/nexus

Source: https://docs.recurso.dev/api-reference/settings/get-nexus

Example response for the GET /v1/settings/tax/nexus endpoint. Returns an array of declared nexus states with state_code, nexus_type, established_at, and created_at fields.

```json
{
  "data": [
    {
      "state_code": "CA",
      "nexus_type": "physical",
      "established_at": "2026-01-01T00:00:00Z",
      "created_at": "2026-01-14T09:30:00Z"
    },
    {
      "state_code": "NY",
      "nexus_type": "economic",
      "established_at": "2026-04-18T00:00:00Z",
      "created_at": "2026-04-18T02:00:00Z"
    }
  ]
}

```

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

### Begin TOTP MFA Setup: Go

Source: https://docs.recurso.dev/api-reference/auth/mfa-setup

Go example using the standard `net/http` package to POST to the MFA setup endpoint with the session cookie in the header.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/auth/mfa/setup"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("cookie", "recurso_session=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Ruby Example

Source: https://docs.recurso.dev/api-reference/invoices/payment-wall

Ruby example using net/http to make the GET request.

```ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/invoices/{id}/payment-wall")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

```

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

### Update card on file (Stripe SetupIntent)

Source: https://docs.recurso.dev/portal/self-service

Three-step process to update the card on file using a Stripe SetupIntent. Start by creating a setup intent to get a client_secret, then confirm the SetupIntent in the browser with Stripe.js, and finally finalize by sending the setup_intent_id to the confirm endpoint.

```bash
# 1. Start — returns a client_secret for Stripe Elements
curl -X POST https://billing.example.com/portal/api/payment-method/setup-intent \
  -b cookies.txt

# 2. (browser) confirm the SetupIntent with Stripe.js using client_secret

# 3. Finalize — saves the card metadata on the customer
curl -X POST https://billing.example.com/portal/api/payment-method/confirm \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{ "setup_intent_id": "seti_..." }'
```

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

### Go request to start ACH bank-account setup

Source: https://docs.recurso.dev/api-reference/portal/payment-method-bank-setup-intent

Uses the net/http package to POST to the bank-setup-intent endpoint. Adds the `cookie` header with the portal session. Prints the response body.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/portal/api/payment-method/bank-setup-intent"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("cookie", "portal_session=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Go example for customer wallets

Source: https://docs.recurso.dev/api-reference/wallets/customer-wallets

Go example using net/http to fetch customer wallets. Includes error handling.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/customers/{id}/wallets"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### PHP cURL example for GET /v1/billing/status

Source: https://docs.recurso.dev/api-reference/billing/get-status

PHP example using cURL to make the GET request. Replace <token> with your bearer token. Outputs the response or a cURL error message.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/billing/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

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

### GET /v1/ledger/deferred-rollforward

Source: https://docs.recurso.dev/api-reference/ledger/deferred-rollforward

Documentation for the GET /v1/ledger/deferred-rollforward endpoint, including request and response examples.

```APIDOC
## GET /v1/ledger/deferred-rollforward

### Description
Returns the movement of the Deferred Revenue account (code `2100`) over a calendar month, sourced straight from the ledger: the balance carried in at the start of the month, new deferrals booked during it (credits), amounts recognized or reversed out of it (debits), and the closing balance. The identity is always `opening + added - released == closing`. This is the rollforward an auditor ties to the Deferred Revenue line of the trial balance.

### Method
GET

### Endpoint
`/v1/ledger/deferred-rollforward`

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Example
```
curl --request GET \
  --url https://billing.example.com/v1/ledger/deferred-rollforward \
  --header 'Authorization: Bearer <token>'
```

### Response
#### Success Response (200)
- **data** (object) - The rollforward data.

#### Response Example
```
{
  "data": {}
}
```

#### Error Response (400)
- **error** (object) - Error details.
  - **code** (string) - Error code.
  - **message** (string) - Error message.

#### Error Response Example
```
{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}
```

#### Error Response (401)
- **error** (object) - Error details.
  - **code** (string) - Error code.
  - **message** (string) - Error message.

#### Error Response Example
```
{
  "error": {
    "code": "validation_failed",
    "message": "<string>"
  }
}
```
```

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

### Go HTTP request to confirm a SetupIntent

Source: https://docs.recurso.dev/api-reference/portal/payment-method-confirm

Go example using net/http to POST the setup_intent_id to the confirm endpoint. Requires an active portal session cookie.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/portal/api/payment-method/confirm"

	payload := strings.NewReader("{\n  \"setup_intent_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("cookie", "portal_session=")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### GET /v1/analytics/revenue-by-plan request examples

Source: https://docs.recurso.dev/api-reference/analytics/revenue-by-plan

Example requests for the GET /v1/analytics/revenue-by-plan endpoint in cURL, Python, JavaScript, PHP, Go, Java, and Ruby. All use the same URL and require an Authorization header with a bearer token.

```cURL
curl --request GET \
  --url https://billing.example.com/v1/analytics/revenue-by-plan \
  --header 'Authorization: Bearer <token>'
```

```Python
import requests

url = "https://billing.example.com/v1/analytics/revenue-by-plan"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

```JavaScript
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://billing.example.com/v1/analytics/revenue-by-plan', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/analytics/revenue-by-plan",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/analytics/revenue-by-plan"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

```Java
HttpResponse<String> response = Unirest.get("https://billing.example.com/v1/analytics/revenue-by-plan")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```Ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/analytics/revenue-by-plan")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

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

### Get a plan with Go

Source: https://docs.recurso.dev/api-reference/plans/get

Go example using net/http to fetch a plan. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/plans/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Get a plan with cURL

Source: https://docs.recurso.dev/api-reference/plans/get

cURL example for the Get a plan endpoint. Uses a placeholder ID and token.

```bash
curl --request GET \
  --url https://billing.example.com/v1/plans/{id} \
  --header 'Authorization: Bearer <token>'

```

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

### Go: GET entities-overview

Source: https://docs.recurso.dev/api-reference/analytics/entities-overview

Go example using net/http to fetch the entities overview.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/analytics/entities-overview"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Begin TOTP MFA Setup: Python

Source: https://docs.recurso.dev/api-reference/auth/mfa-setup

Python example using the `requests` library to POST to the MFA setup endpoint with the session cookie in the headers.

```python
import requests

url = "https://billing.example.com/v1/auth/mfa/setup"

headers = {"cookie": "recurso_session="}

response = requests.post(url, headers=headers)

print(response.text)

```

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

### 200 response example

Source: https://docs.recurso.dev/api-reference/disputes/get

Example JSON response for a successful GET request, showing the dispute object fields.

```json
{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reason": "<string>",
    "status": "open",
    "note": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "resolved_at": "2023-11-07T05:31:56Z"
  }
}
```

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

### Begin TOTP MFA Setup: Ruby

Source: https://docs.recurso.dev/api-reference/auth/mfa-setup

Ruby example using the `net/http` library to POST to the MFA setup endpoint with the session cookie in the header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/v1/auth/mfa/setup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cookie"] = 'recurso_session='

response = http.request(request)
puts response.read_body

```

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

### Example response for Get GST configuration

Source: https://docs.recurso.dev/api-reference/gst/get-config

Example response body for a successful GET request. Contains GST details such as GSTIN, legal name, state code, SAC code, GST rate, and e-invoice status.

```json
{
  "gstin": "29AABCT1332L1ZM",
  "legal_name": "Recurso Technologies Pvt Ltd",
  "trade_name": "Recurso",
  "state_code": "29",
  "sac_code": "998314",
  "gst_rate": 18.0,
  "einvoice_enabled": true,
  "created_at": "2025-08-12T06:30:00Z",
  "updated_at": "2026-03-15T10:45:22Z"
}
```

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

### Get Tenant Account with Go

Source: https://docs.recurso.dev/api-reference/account/get

Go example using net/http to fetch the tenant account. Replace <token> with your API key.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/account"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Worked example: $20 to $50 upgrade on day 10

Source: https://docs.recurso.dev/core/proration

Worked example: upgrading from $20/mo to $50/mo on day 10 of a 30-day cycle. Shows the net charge of $20.00 billed immediately; reversing the prices yields a $20.00 credit note.

```text
remaining / total = 20 / 30  =  0.6667   (⅔ of the cycle left)

credit  = trunc( 2000 × 20/30 )  = trunc(1333.33)  = 1333   →  $13.33
charge  = trunc( 5000 × 20/30 )  = trunc(3333.33)  = 3333   →  $33.33
net     = 3333 − 1333            = 2000             →  $20.00  billed now
```

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

### Go example to get a dispute

Source: https://docs.recurso.dev/api-reference/disputes/get

Uses the net/http package to send a GET request and print the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/disputes/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Get a customer (Java Unirest)

Source: https://docs.recurso.dev/api-reference/customers/get

Java example using Unirest to GET a customer. Returns the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://billing.example.com/v1/customers/{id}")
  .header("Authorization", "Bearer <token>")
  .asString();

```

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

### List plans with Go

Source: https://docs.recurso.dev/api-reference/plans/list

Go example using net/http to list plans. Creates a GET request with a Bearer token and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/plans?limit=50&page=1"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Go: Begin TOTP MFA setup

Source: https://docs.recurso.dev/api-reference/auth/mfa-setup

Uses net/http to POST to the MFA setup endpoint with a session cookie and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/auth/mfa/setup"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("cookie", "recurso_session=")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Get a customer (cURL)

Source: https://docs.recurso.dev/api-reference/customers/get

cURL example for the Get a customer endpoint. Uses the `Authorization: Bearer <token>` header.

```bash
curl --request GET \
  --url https://billing.example.com/v1/customers/{id} \
  --header 'Authorization: Bearer <token>'

```

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

### cURL: GET entities-overview

Source: https://docs.recurso.dev/api-reference/analytics/entities-overview

cURL example for the multi-entity control tower endpoint. Uses GET with an Authorization header.

```bash
curl --request GET \
  --url https://billing.example.com/v1/analytics/entities-overview \
  --header 'Authorization: Bearer <token>'

```

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

### Start a card update with Ruby

Source: https://docs.recurso.dev/api-reference/portal/payment-method-setup-intent

Ruby example using Net::HTTP to POST to the setup-intent endpoint with the portal session cookie.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/portal/api/payment-method/setup-intent")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["cookie"] = 'portal_session='

response = http.request(request)
puts response.read_body
```

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

### 200 response example for GET /v1/payment-attempts

Source: https://docs.recurso.dev/api-reference/payment-attempts/list

Example JSON response showing a list of payment attempts with pagination metadata.

```json
{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "invoice_number": "<string>",
      "currency": "<string>",
      "gateway": "<string>",
      "method": "<string>",
      "gateway_payment_intent_id": "<string>",
      "status": "initiated",
      "failure_code": "<string>",
      "amount": 123,
      "created_at": "2023-11-07T05:31:56Z",
      "settled_at": "2023-11-07T05:31:56Z"
    }
  ],
  "pagination": {
    "page": 123,
    "per_page": 123,
    "total": 123,
    "total_pages": 123
  }
}
```

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

### Install with Docker Compose

Source: https://docs.recurso.dev/quickstart

Clone the repository and start the full stack with Docker Compose. The API becomes available at http://localhost:8080.

```bash
# Clone the repository
git clone https://github.com/recurso-dev/recurso.git
cd recurso

# Start with Docker Compose
docker-compose up -d

# API available at http://localhost:8080

```

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

### Java Unirest example

Source: https://docs.recurso.dev/api-reference/analytics/dunning-recovered

Java example using Unirest to GET the endpoint. Replace <token> with your API key.

```java
HttpResponse<String> response = Unirest.get("https://billing.example.com/v1/analytics/dunning/recovered")
  .header("Authorization", "Bearer <token>")
  .asString();

```

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

### Fetch a wallet with Go

Source: https://docs.recurso.dev/api-reference/wallets/get

Go example using the net/http package to fetch a wallet. Creates a GET request with the Authorization header, performs the request, and prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/wallets/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### PHP cURL example

Source: https://docs.recurso.dev/api-reference/analytics/dunning-recovered

PHP example using cURL to GET the endpoint. Replace <token> with your API key.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/v1/analytics/dunning/recovered",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

```

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

### Go example

Source: https://docs.recurso.dev/api-reference/wallets/close

Go example using net/http to close a wallet.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/wallets/{id}/close"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Example Request: GET /v1/accounting/sync/status

Source: https://docs.recurso.dev/api-reference/accounting/sync-status

Example request to the sync status endpoint using a live API key.

```bash
curl -X GET "https://api.recurso.dev/v1/accounting/sync/status" \
  -H "Authorization: Bearer rsk_live_9f8a7b6c5d4e3f2a1b0c"
```

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

### Go example

Source: https://docs.recurso.dev/api-reference/organizations/add-tenant

Uses net/http to POST the tenant_id. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/organizations/{id}/tenants"

	payload := strings.NewReader("{\n  \"tenant_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### OAuth start with Ruby

Source: https://docs.recurso.dev/api-reference/auth/oauth-start

Ruby example using net/http to call the OAuth start endpoint with an Authorization header.

```ruby
require 'uri'
require 'net/http'

url = URI("https://billing.example.com/auth/oauth/{provider}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<api-key>'

response = http.request(request)
puts response.read_body

```

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

### Begin TOTP MFA Setup: JavaScript

Source: https://docs.recurso.dev/api-reference/auth/mfa-setup

JavaScript example using the Fetch API to POST to the MFA setup endpoint with the session cookie in the headers.

```javascript
const options = {method: 'POST', headers: {cookie: 'recurso_session='}};

fetch('https://billing.example.com/v1/auth/mfa/setup', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

```

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

### Go net/http example for GET /v1/analytics/dunning/weights

Source: https://docs.recurso.dev/api-reference/analytics/dunning-weights

Go example using net/http to fetch dunning weights. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/analytics/dunning/weights"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

```

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

### Go GET /v1/usage/dimensions

Source: https://docs.recurso.dev/api-reference/usage/dimensions

Go example using net/http to GET the usage dimensions catalog. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/usage/dimensions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

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

### Get subscription by id (cURL)

Source: https://docs.recurso.dev/api-reference/subscriptions/get

cURL example for the 'Get a subscription by id' endpoint. Uses a placeholder token and ID.

```bash
curl --request GET \
  --url https://billing.example.com/v1/subscriptions/{id} \
  --header 'Authorization: Bearer <token>'

```

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

### Create SetupIntent with X-Portal-Session header

Source: https://docs.recurso.dev/api-reference/portal/payment-method-setup-intent

Creates a Stripe SetupIntent for updating a payment method. The request requires the X-Portal-Session header with a customer-portal session token. The response contains the client_secret and publishable_key needed to complete the card update.

```bash
curl -X POST https://api.recurso.dev/portal/api/payment-method/setup-intent \
  -H "X-Portal-Session: <session token>"
```

```json
{
  "data": {
    "client_secret": "seti_1Tra..._secret_...",
    "publishable_key": "pk_live_..."
  }
}
```

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

### Java Unirest GET /v1/settings/mcp

Source: https://docs.recurso.dev/api-reference/settings/get-mcp

Java example using Unirest to perform a GET request and receive the response as a string.

```java
HttpResponse<String> response = Unirest.get("https://billing.example.com/v1/settings/mcp")
  .header("Authorization", "Bearer <token>")
  .asString();
```

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

### Go example to start a cancel flow session

Source: https://docs.recurso.dev/api-reference/cancel-flows/start-session

Uses net/http to POST the customer_id and subscription_id. Prints the response body.

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/v1/cancel-flows/sessions/start"

	payload := strings.NewReader("{\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"subscription_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```
Tokens:
Raw