# Invoice

## Show Invoice

<mark style="color:blue;">`GET`</mark> `https://app.clubcollect.com/api/v2/invoices/:id`

Fetch Invoice details.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Invoice ID  |

#### Query Parameters

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| api:key | string | Partner API Key (Deprecated) |

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | ApiKey \<api\_key>          |
| Content-Type                                    | string | Must be `application/json`. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },        
    {
      "invoice_line_id": "...",           
      "type": "CREDIT-LINE",            
      "amount_cents": -1000,           
      "description": "Deduction",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "CHARGEBACK-LINE",            
      "amount_cents": 123,           
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",           
      "type": "CHARGEBACK-FEE-LINE",            
      "amount_cents": 123,           
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "CHARGEBACK-FEE-PAYMENT-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "LATE-PAYMENT-FEE-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "LATE-PAYMENT-FEE-PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "INSTALLMENT-FEE-LINE",            
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    },        
    {          
      "invoice_line_id": "...",            
      "type": "INSTALLMENT-FEE-PAYMENT-LINE",
      "payment_method": "ideal|bacs|bancontact|credit_card|sdd|bank_transfer",
      "amount_cents": 123,            
      "description": "...",            
      "date": "..."        
    }    
  ],
  "amount_total_cents": "...",
  "messages": [
    {
      "message_id": "...",
      "type": "EMAIL|SMS|LETTER",
      "description": "...",
      "date": "..."
    },
    {
      "message_id": "...",
      "type": "EMAIL|SMS|LETTER",
      "description": "...",
      "date": "..."}
  ],
  "tickets": [
    {
      "ticket_id": "...",
      "message": "I don't want to pay",
      "sender": "CUSTOMER",
      "date": "..."
    },
    {
      "ticket_id": "...",
      "message": "You really must pay",
      "sender": "COMPANY",
      "date": "..."}
  ],
  "retracted_at": null | "...",
  "retraction_reason": null | "...",
  "show_retraction_reason_to_customer": true | false
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "error": "invalid_invoice_id"
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note** the date format is `ISO 8601`.
{% endhint %}

{% hint style="info" %}
**Note** a Partner usually calls the `GET /v2/invoices/:id` method in response to a notification sent by ClubCollect about an update to an Invoice.
{% endhint %}

{% hint style="info" %}
**Note** To get a list of possible values for invoice lines types see the Invoice Line documentation.
{% endhint %}

## Create Invoice

<mark style="color:green;">`POST`</mark> `https://app.clubcollect.com/api/v2/invoices`

Create an Invoice with one or more Invoice Lines.

#### Query Parameters

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| api:key | string | Partner API Key (Deprecated) |

#### Headers

| Name                                            | Type   | Description                  |
| ----------------------------------------------- | ------ | ---------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | ApiKey \<api\_key>           |
| Content-Type<mark style="color:red;">\*</mark>  | string | Must be: `application/json`. |

#### Request Body

| Name                                                            | Type   | Description                                                                                                                                                                                            |
| --------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| locale                                                          | string | When supplied, the invoice's locale will be set to this value. From `{ de en fr it nl }`                                                                                                               |
| direct:debit:iban                                               | string | When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.                                                                                                                   |
| federation:membership:number                                    | string |                                                                                                                                                                                                        |
| club:membership:number                                          | string |                                                                                                                                                                                                        |
| member:external:id                                              | string |                                                                                                                                                                                                        |
| external:membership:number                                      | string |                                                                                                                                                                                                        |
| invoice:lines\[].invoice:line:id                                | string | Optionally specify a custom identifier to overwrite an otherwise randomly generated identifier. If given, the partner must ensure that the ID is unique. Requests with duplicate IDs will be rejected. |
| amount:total:cents<mark style="color:red;">\*</mark>            | number | Must be equal to the sum of the amounts of the Invoice Lines. May be zero or negative.                                                                                                                 |
| invoice:lines<mark style="color:red;">\*</mark>                 | array  |                                                                                                                                                                                                        |
| customer.address.country:code<mark style="color:red;">\*</mark> | string | May be empty if \`email\_address\` or \`phone\_number\` is provided                                                                                                                                    |
| customer.address.city<mark style="color:red;">\*</mark>         | string | May be empty if \`email\_address\` or \`phone\_number\` is provided                                                                                                                                    |
| customer.address.zipcode<mark style="color:red;">\*</mark>      | string | May be empty if \`email\_address\` or \`phone\_number\` is provided                                                                                                                                    |
| customer.address.address1<mark style="color:red;">\*</mark>     | string | May be empty if \`email\_address\` or \`phone\_number\` is provided                                                                                                                                    |
| customer.address.address2                                       | string |                                                                                                                                                                                                        |
| customer.address.house:number                                   | string |                                                                                                                                                                                                        |
| customer.address.house:number:extension                         | string |                                                                                                                                                                                                        |
| customer.address.locality                                       | string |                                                                                                                                                                                                        |
| customer.address.state                                          | string |                                                                                                                                                                                                        |
| customer.phone.country:code<mark style="color:red;">\*</mark>   | string | May be empty if \`email\_address\` or a postal address is provided                                                                                                                                     |
| customer.phone.phone:number<mark style="color:red;">\*</mark>   | string | May be empty if \`email\_address\` or a postal address is provided                                                                                                                                     |
| customer.email.email:address<mark style="color:red;">\*</mark>  | string | May be empty if \`phone\_number\` or a postal address is provided                                                                                                                                      |
| customer.name.prefix                                            | string |                                                                                                                                                                                                        |
| customer.name.first:name                                        | string |                                                                                                                                                                                                        |
| customer.name.infix                                             | string |                                                                                                                                                                                                        |
| customer.name.last:name<mark style="color:red;">\*</mark>       | string |                                                                                                                                                                                                        |
| customer.name.organization                                      | string |                                                                                                                                                                                                        |
| external:invoice:number<mark style="color:red;">\*</mark>       | string |                                                                                                                                                                                                        |
| reference                                                       | string |                                                                                                                                                                                                        |
| import:id<mark style="color:red;">\*</mark>                     | string | ID of Import to which the Invoice should belong.                                                                                                                                                       |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}
```

{% endtab %}
{% endtabs %}

## Example Request Body

```javascript
{
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "locale": "en",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000
}
```

## Error Messages

* `invalid_import_id`: No import with this ID could be found.
* `invalid_external_invoice_number`: formatting error: min. 1 character.
* `invalid_customer_last_name`: Last name may not be empty.
* `invalid_customer_email`: Email address may not be empty if no phone number is provided.
* `invalid_customer_phone`: Phone number may not be empty if no email address is provided.
* `invalid_customer_address`: Address may not be empty if neither an email address nor phone number is provided.
* `invalid_amount_total_cents`: `amount_total_cents` is not equal to the total of all invoice line amounts.
* `duplicate_invoice_line_id`: The `duplicate_invoice_line_id` provided was already used for another invoice line.
* `invalid_content_type`: `Content-Type: application/json` must be provided.

{% hint style="info" %}
**Note** the total may be zero (nothing to receive) or negative (something to receive).
{% endhint %}

{% hint style="info" %}
**Note** at least one of:

* `customer.email.email_address`
* `customer.phone.*`
* `customer.address.*`

must be provided. i.e. there must be a way for us to contact the Customer via email, phone or postal mail.
{% endhint %}

{% hint style="info" %}
**Note** It's not possible to add or delete invoice lines for an existing invoice. If an invoice is incorrectly created with a wrong amount outstanding (or the invoice becomes invalid for some reason after it's transmitted), the partner can credit it using `/credit_and_retract` endpoint.
{% endhint %}

## Update Invoice

<mark style="color:orange;">`PUT`</mark> `https://app.clubcollect.com/api/v2/invoices/:id`

Update a subset of Invoice attributes.

**Note** The invoice lines can't be updated, only the attributes relative to the recipient of the invoice can be updated.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Invoice ID  |

#### Query Parameters

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| api:key | string | Partner API Key (Deprecated) |

#### Headers

| Name                                            | Type   | Description                  |
| ----------------------------------------------- | ------ | ---------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | ApiKey \<api\_key>           |
| Content-Type<mark style="color:red;">\*</mark>  | string | Must be: `application/json`. |

#### Request Body

| Name                                                      | Type   | Description                                                                              |
| --------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| locale                                                    | string | When supplied, the invoice's locale will be set to this value. From `{ de en fr it nl }` |
| direct:debit:iban                                         | string | When supplied, will be accepted and added to the Invoice only if it is a valid IBAN.     |
| federation:membership:number                              | string |                                                                                          |
| club:membership:number                                    | string |                                                                                          |
| member:external:id                                        | string |                                                                                          |
| external:membership:number                                | string |                                                                                          |
| customer.address.country:code                             | string |                                                                                          |
| customer.address.city                                     | string |                                                                                          |
| customer.address.zipcode                                  | string |                                                                                          |
| customer.address.address1                                 | string |                                                                                          |
| customer.address.address2                                 | string |                                                                                          |
| customer.address.house:number                             | string |                                                                                          |
| customer.address.house:number:extension                   | string |                                                                                          |
| customer.address.locality                                 | string |                                                                                          |
| customer.address.state                                    | string |                                                                                          |
| customer.phone.country:code                               | string |                                                                                          |
| customer.phone.phone:number                               | string |                                                                                          |
| customer.email.email:address                              | string |                                                                                          |
| customer.name.last:name                                   | string |                                                                                          |
| customer.name.organization                                | string |                                                                                          |
| external:invoice:number<mark style="color:red;">\*</mark> | string |                                                                                          |
| reference                                                 | string |                                                                                          |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "error": "invalid_invoice_id"
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
  "error": "invalid_external_invoice_number"
}
```

{% endtab %}
{% endtabs %}

## Example Request Body

```javascript
{
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
}
```

## Error Messages

* `invalid_invoice_id`: No invoice with this `invoice_id` could be found.
* `invalid_external_invoice_number`: formatting error: min. 1 character.
* `invalid_customer_last_name`: Last name may not be empty.
* `invalid_customer_email`: Email address may not be empty if no phone number is provided.
* `invalid_customer_phone`: Phone number may not be empty if no email address is provided.
* `invalid_content_type`: `Content-Type: application/json` must be provided.

## Credit and Retract Invoice

<mark style="color:green;">`POST`</mark> `https://app.clubcollect.com/api/v2/invoices/:id/credit:and:retract`

Call this method to credit the total outstanding amount of an invoice and retract it in a single HTTP request. Any payment decision made for the invoice will be cancelled. Additional fees that might be due will be credited automatically. It won't be possible to apply more credits to the invoice.

#### Path Parameters

| Name                                 | Type   | Description                        |
| ------------------------------------ | ------ | ---------------------------------- |
| id<mark style="color:red;">\*</mark> | string | ID of the Invoice to be retracted. |

#### Query Parameters

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| api:key | string | Partner API Key (Deprecated) |

#### Headers

| Name                                            | Type   | Description                 |
| ----------------------------------------------- | ------ | --------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | ApiKey \<api\_key>          |
| Content-Type<mark style="color:red;">\*</mark>  | string | Must be `application/json`. |

#### Request Body

| Name                                                      | Type    | Description |
| --------------------------------------------------------- | ------- | ----------- |
| show:retraction:reason:to:customer                        | boolean |             |
| external:invoice:number<mark style="color:red;">\*</mark> | string  |             |
| retraction:reason                                         | string  |             |
| description<mark style="color:red;">\*</mark>             | string  |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "invoice_id": "...",
  "import_id": "...",
  "external_invoice_number": "2014-342-545",
  "reference": "ba6fe77",
  "invoice_number": "123456",
  "direct_debit_iban": "...",
  "federation_membership_number": "...",
  "club_membership_number": "...",
  "member_external_id": "...",
  "external_membership_number": "...",
  "customer": {
    "name": {
      "prefix": "Mr",
      "first_name": "Joe",
      "infix": "van der",
      "last_name": "Doe",
      "organization": "TheClub"
    },
    "address": {
      "address1": "3rd Avenue",
      "address2": "",
      "locality": "",
      "house_number": "1500",
      "state": "",
      "zipcode": "10010",
      "city": "Amsterdam",
      "country_code": "NL"
    },
    "email": {
      "email_address": "joe@example.com"
    },
    "phone": {
      "phone_number": "562-756-2233",
      "country_code": "NL"
    }
  },
  "invoice_lines": [        
    {
      "invoice_line_id": "...",            
      "type": "INVOICE-LINE",            
      "amount_cents": 10000,            
      "description": "Membership fee",            
      "date": "..."        
    },
    {
      "invoice_line_id": "...",
      "amount_cents": -1000,
      "description": "Deduction",
      "date": "..."
    }
  ],
  "amount_total_cents": 9000,
  "tickets": [],
  "messages": []
}
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "error": "invalid_invoice_id"
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
  "error": "payment_in_progress"
}
```

{% endtab %}
{% endtabs %}

## Example Request Body

```javascript
{
  "external_invoice_number": "2014-342-545",
  "description": "Cash payment",
  "retraction_reason": "Paid by cash",
  "show_retraction_reason_to_customer": true
}
```

## Error Messages

* `invalid_invoice_id`: No invoice with this ID could be found.
* `invalid_external_invoice_number`: min. 1 character
* `invalid_description`: `description` must be provided.
* `already_retracted`: The invoice with this ID has already been retracted.
* `invalid_content_type`: `Content-Type: application/json` must be provided.
* `payment_in_progress`: An invoice can't be credited or retracted if there's a payment in progress

## Delete Invoice

<mark style="color:red;">`DELETE`</mark> `https://app.clubcollect.com/api/v2/invoices/:id`

Deletes an invoice. Deleting an invoice is possible only when it's not transmitted yet.

#### Path Parameters

| Name                                 | Type   | Description |
| ------------------------------------ | ------ | ----------- |
| id<mark style="color:red;">\*</mark> | string | Invoice ID  |

#### Query Parameters

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| api:key | string | Partner API Key (Deprecated) |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | string | ApiKey \<api\_key> |

{% tabs %}
{% tab title="204 " %}

```
```

{% endtab %}

{% tab title="404 " %}

```javascript
{
  "error": "invalid_invoice_id"
}
```

{% endtab %}

{% tab title="422 " %}

```javascript
{
  "error": "invoice_already_transmitted"
}
```

{% endtab %}
{% endtabs %}


---

# 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://docs.clubcollect.com/api-documentation/invoice.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.