Skip to main content
POST
/
v2
/
invoicing
/
invoices
Create draft invoice
curl --request POST \
  --url https://api-m.sandbox.paypal.com/v2/invoicing/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "detail": {
    "currency_code": "<string>",
    "reference": "<string>",
    "note": "<string>",
    "terms_and_conditions": "<string>",
    "memo": "<string>",
    "attachments": [
      {
        "id": "<string>",
        "reference_url": "<string>",
        "content_type": "<string>",
        "create_time": "<string>",
        "size": "<string>"
      }
    ],
    "invoice_number": "<string>",
    "invoice_date": "<string>",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT",
      "due_date": "<string>"
    }
  },
  "invoicer": {
    "business_name": "<string>",
    "name": {
      "prefix": "<string>",
      "given_name": "<string>",
      "surname": "<string>",
      "middle_name": "<string>",
      "suffix": "<string>",
      "alternate_full_name": "<string>",
      "full_name": "<string>"
    },
    "address": {
      "country_code": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "address_line_3": "<string>",
      "admin_area_4": "<string>",
      "admin_area_3": "<string>",
      "admin_area_2": "<string>",
      "admin_area_1": "<string>",
      "postal_code": "<string>",
      "address_details": {
        "street_number": "<string>",
        "street_name": "<string>",
        "street_type": "<string>",
        "delivery_service": "<string>",
        "building_name": "<string>",
        "sub_building": "<string>"
      }
    },
    "email_address": "<string>",
    "phones": [
      {
        "country_code": "<string>",
        "national_number": "<string>",
        "phone_type": "FAX",
        "extension_number": "<string>"
      }
    ],
    "website": "<string>",
    "tax_id": "<string>",
    "additional_notes": "<string>",
    "logo_url": "<string>"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "business_name": "<string>",
        "name": {
          "prefix": "<string>",
          "given_name": "<string>",
          "surname": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "alternate_full_name": "<string>",
          "full_name": "<string>"
        },
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "address_line_3": "<string>",
          "admin_area_4": "<string>",
          "admin_area_3": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "address_details": {
            "street_number": "<string>",
            "street_name": "<string>",
            "street_type": "<string>",
            "delivery_service": "<string>",
            "building_name": "<string>",
            "sub_building": "<string>"
          }
        },
        "email_address": "<string>",
        "phones": [
          {
            "country_code": "<string>",
            "national_number": "<string>",
            "phone_type": "FAX",
            "extension_number": "<string>"
          }
        ],
        "additional_info": "<string>",
        "language": "<string>"
      },
      "shipping_info": {
        "business_name": "<string>",
        "name": {
          "prefix": "<string>",
          "given_name": "<string>",
          "surname": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "alternate_full_name": "<string>",
          "full_name": "<string>"
        },
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "address_line_3": "<string>",
          "admin_area_4": "<string>",
          "admin_area_3": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "address_details": {
            "street_number": "<string>",
            "street_name": "<string>",
            "street_type": "<string>",
            "delivery_service": "<string>",
            "building_name": "<string>",
            "sub_building": "<string>"
          }
        }
      }
    }
  ],
  "additional_recipients": [
    "<string>"
  ],
  "items": [
    {
      "name": "<string>",
      "quantity": "<string>",
      "unit_amount": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "description": "<string>",
      "tax": {
        "name": "<string>",
        "percent": "<string>",
        "tax_note": "<string>"
      },
      "item_date": "<string>",
      "discount": {
        "percent": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "tax_calculated_after_discount": true,
    "tax_inclusive": false,
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": false,
      "minimum_amount_due": {
        "currency_code": "<string>",
        "value": "<string>"
      }
    },
    "has_conditional_rule": false,
    "template_id": "PayPal system template"
  },
  "amount": {
    "currency_code": "<string>",
    "value": "<string>",
    "breakdown": {
      "item_total": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "discount": {
        "invoice_discount": {
          "percent": "<string>",
          "amount": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        },
        "item_discount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      },
      "tax_total": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "shipping": {
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "tax": {
          "name": "<string>",
          "percent": "<string>",
          "tax_note": "<string>"
        }
      },
      "custom": {
        "label": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      }
    }
  },
  "payments": {},
  "refunds": {}
}
'
{
  "detail": {
    "currency_code": "<string>",
    "reference": "<string>",
    "note": "<string>",
    "terms_and_conditions": "<string>",
    "memo": "<string>",
    "attachments": [
      {
        "id": "<string>",
        "reference_url": "<string>",
        "content_type": "<string>",
        "create_time": "<string>",
        "size": "<string>"
      }
    ],
    "invoice_number": "<string>",
    "invoice_date": "<string>",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT",
      "due_date": "<string>"
    },
    "metadata": {
      "create_time": "<string>",
      "created_by": "<string>",
      "last_update_time": "<string>",
      "last_updated_by": "<string>",
      "cancel_time": "<string>",
      "cancelled_by": "<string>",
      "first_sent_time": "<string>",
      "last_sent_time": "<string>",
      "last_sent_by": "<string>",
      "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP",
      "recipient_view_url": "<string>",
      "invoicer_view_url": "<string>"
    }
  },
  "id": "<string>",
  "parent_id": "<string>",
  "status": "DRAFT",
  "invoicer": {
    "business_name": "<string>",
    "name": {
      "prefix": "<string>",
      "given_name": "<string>",
      "surname": "<string>",
      "middle_name": "<string>",
      "suffix": "<string>",
      "alternate_full_name": "<string>",
      "full_name": "<string>"
    },
    "address": {
      "country_code": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "address_line_3": "<string>",
      "admin_area_4": "<string>",
      "admin_area_3": "<string>",
      "admin_area_2": "<string>",
      "admin_area_1": "<string>",
      "postal_code": "<string>",
      "address_details": {
        "street_number": "<string>",
        "street_name": "<string>",
        "street_type": "<string>",
        "delivery_service": "<string>",
        "building_name": "<string>",
        "sub_building": "<string>"
      }
    },
    "email_address": "<string>",
    "phones": [
      {
        "country_code": "<string>",
        "national_number": "<string>",
        "phone_type": "FAX",
        "extension_number": "<string>"
      }
    ],
    "website": "<string>",
    "tax_id": "<string>",
    "additional_notes": "<string>",
    "logo_url": "<string>"
  },
  "primary_recipients": [
    {
      "billing_info": {
        "business_name": "<string>",
        "name": {
          "prefix": "<string>",
          "given_name": "<string>",
          "surname": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "alternate_full_name": "<string>",
          "full_name": "<string>"
        },
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "address_line_3": "<string>",
          "admin_area_4": "<string>",
          "admin_area_3": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "address_details": {
            "street_number": "<string>",
            "street_name": "<string>",
            "street_type": "<string>",
            "delivery_service": "<string>",
            "building_name": "<string>",
            "sub_building": "<string>"
          }
        },
        "email_address": "<string>",
        "phones": [
          {
            "country_code": "<string>",
            "national_number": "<string>",
            "phone_type": "FAX",
            "extension_number": "<string>"
          }
        ],
        "additional_info": "<string>",
        "language": "<string>"
      },
      "shipping_info": {
        "business_name": "<string>",
        "name": {
          "prefix": "<string>",
          "given_name": "<string>",
          "surname": "<string>",
          "middle_name": "<string>",
          "suffix": "<string>",
          "alternate_full_name": "<string>",
          "full_name": "<string>"
        },
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "address_line_3": "<string>",
          "admin_area_4": "<string>",
          "admin_area_3": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>",
          "address_details": {
            "street_number": "<string>",
            "street_name": "<string>",
            "street_type": "<string>",
            "delivery_service": "<string>",
            "building_name": "<string>",
            "sub_building": "<string>"
          }
        }
      }
    }
  ],
  "additional_recipients": [
    "<string>"
  ],
  "items": [
    {
      "name": "<string>",
      "quantity": "<string>",
      "unit_amount": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "id": "<string>",
      "description": "<string>",
      "tax": {
        "name": "<string>",
        "percent": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "tax_note": "<string>"
      },
      "item_date": "<string>",
      "discount": {
        "percent": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      },
      "unit_of_measure": "QUANTITY"
    }
  ],
  "configuration": {
    "tax_calculated_after_discount": true,
    "tax_inclusive": false,
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": false,
      "minimum_amount_due": {
        "currency_code": "<string>",
        "value": "<string>"
      }
    },
    "has_conditional_rule": false,
    "template_id": "PayPal system template"
  },
  "amount": {
    "currency_code": "<string>",
    "value": "<string>",
    "breakdown": {
      "item_total": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "discount": {
        "invoice_discount": {
          "percent": "<string>",
          "amount": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        },
        "item_discount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      },
      "tax_total": {
        "currency_code": "<string>",
        "value": "<string>"
      },
      "shipping": {
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "tax": {
          "name": "<string>",
          "percent": "<string>",
          "amount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "tax_note": "<string>"
        }
      },
      "custom": {
        "label": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      }
    }
  },
  "due_amount": {
    "currency_code": "<string>",
    "value": "<string>"
  },
  "gratuity": {
    "currency_code": "<string>",
    "value": "<string>"
  },
  "payments": {
    "paid_amount": {
      "currency_code": "<string>",
      "value": "<string>"
    },
    "transactions": [
      {
        "method": "BANK_TRANSFER",
        "type": "PAYPAL",
        "payment_id": "<string>",
        "payment_date": "<string>",
        "payment_date_time": "<string>",
        "note": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "shipping_info": {
          "business_name": "<string>",
          "name": {
            "prefix": "<string>",
            "given_name": "<string>",
            "surname": "<string>",
            "middle_name": "<string>",
            "suffix": "<string>",
            "alternate_full_name": "<string>",
            "full_name": "<string>"
          },
          "address": {
            "country_code": "<string>",
            "address_line_1": "<string>",
            "address_line_2": "<string>",
            "address_line_3": "<string>",
            "admin_area_4": "<string>",
            "admin_area_3": "<string>",
            "admin_area_2": "<string>",
            "admin_area_1": "<string>",
            "postal_code": "<string>",
            "address_details": {
              "street_number": "<string>",
              "street_name": "<string>",
              "street_type": "<string>",
              "delivery_service": "<string>",
              "building_name": "<string>",
              "sub_building": "<string>"
            }
          }
        }
      }
    ]
  },
  "refunds": {
    "refund_amount": {
      "currency_code": "<string>",
      "value": "<string>"
    },
    "transactions": [
      {
        "method": "BANK_TRANSFER",
        "type": "PAYPAL",
        "refund_id": "<string>",
        "refund_date": "<string>",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      }
    ]
  },
  "links": [
    {
      "href": "<string>",
      "rel": "<string>",
      "method": "GET"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Oauth 2.0 authentication

Body

application/json

The invoice details which includes all information of the invoice like items, billing information.

The invoice details which includes all information of the invoice like items, billing information.

​
detail
Invoice Detail · object
required

The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

​
invoicer
Invoicer Information · object

The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

​
primary_recipients
Recipient Information · object[]

The billing and shipping information. Includes name, email, address, phone and language.

Maximum array length: 100
​
additional_recipients
string<ppaas_common_email_address_v2>[]

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Maximum array length: 100

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

Required string length: 3 - 254
​
items
Invoice Item · object[]

An array of invoice line item information.

Maximum array length: 100
​
configuration
Configuration · object

The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

​
amount
Invoice Amount Summary · object

The invoice amount summary of item total, discount, tax total and shipping..

​
payments
Payments · object

List of payments registered against the invoice..

​
refunds
Refunds · object

List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

Response

A successful request returns the HTTP 201 Created status code. A JSON response body that shows invoice details is returned if you set prefer=return=representation.

The invoice details which includes all information of the invoice like items, billing information.

​
detail
Invoice Detail · object
required

The details of the invoice. Includes the invoice number, date, payment terms, and audit metadata.

​
id
string

The ID of the invoice.

Maximum string length: 30
​
parent_id
string

The parent ID to an invoice that defines the group invoice to which the invoice is related.

Maximum string length: 30
​
status
enum<string>

The status of the invoice.

Available options:
DRAFT,
SENT,
SCHEDULED,
PAID,
MARKED_AS_PAID,
CANCELLED,
REFUNDED,
PARTIALLY_PAID,
PARTIALLY_REFUNDED,
MARKED_AS_REFUNDED,
UNPAID,
PAYMENT_PENDING,
AUTO_CANCELLED,
PAID_EXTERNAL,
REFUNDED_EXTERNAL,
SHARED
Maximum string length: 255
​
invoicer
Invoicer Information · object

The invoicer information. Includes the business name, email, address, phone, fax, tax ID, additional notes, and logo URL.

​
primary_recipients
Recipient Information · object[]

The billing and shipping information. Includes name, email, address, phone and language.

Maximum array length: 100
​
additional_recipients
string<ppaas_common_email_address_v2>[]

An array of one or more CC: emails to which notifications are sent. If you omit this parameter, a notification is sent to all CC: email addresses that are part of the invoice.

Note: Valid values are email addresses in the additional_recipients value associated with the invoice.

Maximum array length: 100

The internationalized email address.

Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.

Required string length: 3 - 254
​
items
Invoice Item · object[]

An array of invoice line item information.

Maximum array length: 100
​
configuration
Configuration · object

The invoice configuration details. Includes partial payment, tip, and tax calculated after discount.

​
amount
Invoice Amount Summary · object

The invoice amount summary of item total, discount, tax total and shipping..

​
due_amount
Money · object

The due amount, which is the balance amount outstanding after payments.

​
gratuity
Money · object

The amount paid by the payer as gratuity to the invoicer.

​
payments
Payments · object

List of payments registered against the invoice..

​
refunds
Refunds · object

List of refunds against this invoice. The invoicing refund details includes refund type, date, amount, and method.

​
links
Link Description · object[]

An array of request-related HATEOAS links.

Maximum array length: 2147483647