Create draft invoice

Creates a draft invoice. To move the invoice from a draft to payable state, you must send the invoice.

In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.

Note: The merchant that you specify in an invoice must have a PayPal account in good standing.

Authorization

AuthorizationBearer <token>

Oauth 2.0 authentication

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

For managing (Create, Update, Delete) invoice.https://uri.paypal.com/services/invoicing/invoices/readwrite

Request Body

application/json

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

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://api-m.sandbox.paypal.com/v2/invoicing/invoices" \  -H "Content-Type: application/json" \  -d '{    "detail": {      "currency_code": "str"    }  }'

{
  "id": "string",
  "parent_id": "string",
  "status": "DRAFT",
  "detail": {
    "reference": "string",
    "currency_code": "str",
    "note": "string",
    "terms_and_conditions": "string",
    "memo": "string",
    "attachments": [],
    "invoice_number": "string",
    "invoice_date": "stringstri",
    "payment_term": {
      "term_type": "DUE_ON_RECEIPT",
      "due_date": "stringstri"
    },
    "metadata": {
      "create_time": "stringstringstringst",
      "created_by": "string",
      "last_update_time": "stringstringstringst",
      "last_updated_by": "string",
      "cancel_time": "stringstringstringst",
      "cancelled_by": "string",
      "first_sent_time": "stringstringstringst",
      "last_sent_time": "stringstringstringst",
      "last_sent_by": "string",
      "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP",
      "recipient_view_url": "http://example.com",
      "invoicer_view_url": "http://example.com"
    }
  },
  "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": {
      "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",
      "country_code": "st",
      "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": "str",
        "national_number": "string",
        "extension_number": "string",
        "phone_type": "FAX"
      }
    ],
    "website": "http://example.com",
    "tax_id": "string",
    "additional_notes": "string",
    "logo_url": "http://example.com"
  },
  "primary_recipients": [],
  "additional_recipients": [],
  "items": [],
  "configuration": {
    "tax_calculated_after_discount": true,
    "tax_inclusive": false,
    "allow_tip": false,
    "partial_payment": {
      "allow_partial_payment": false,
      "minimum_amount_due": {
        "currency_code": "str",
        "value": "string"
      }
    },
    "has_conditional_rule": false,
    "template_id": "PayPal system template"
  },
  "amount": {
    "currency_code": "str",
    "value": "string",
    "breakdown": {
      "item_total": {
        "currency_code": "str",
        "value": "string"
      },
      "discount": {
        "invoice_discount": {
          "percent": "string",
          "amount": {
            "currency_code": "str",
            "value": "string"
          }
        },
        "item_discount": {
          "currency_code": "str",
          "value": "string"
        }
      },
      "tax_total": {
        "currency_code": "str",
        "value": "string"
      },
      "shipping": {
        "amount": {
          "currency_code": "str",
          "value": "string"
        },
        "tax": {
          "name": "string",
          "percent": "string",
          "amount": {
            "currency_code": "str",
            "value": "string"
          },
          "tax_note": "string"
        }
      },
      "custom": {
        "label": "string",
        "amount": {
          "currency_code": "str",
          "value": "string"
        }
      }
    }
  },
  "due_amount": {
    "currency_code": "str",
    "value": "string"
  },
  "gratuity": {
    "currency_code": "str",
    "value": "string"
  },
  "payments": {
    "paid_amount": {
      "currency_code": "str",
      "value": "string"
    },
    "transactions": []
  },
  "refunds": {
    "refund_amount": {
      "currency_code": "str",
      "value": "string"
    },
    "transactions": []
  },
  "links": []
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "INVALID_STRING_MAX_LENGTH",
      "description": "Address line2 length should be less than 300 characters."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "description": "string"
    }
  ],
  "debug_id": "string",
  "links": []
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "string",
  "links": [],
  "details": [
    {
      "issue": "USER_NOT_FOUND",
      "description": "User is not associated with paypal based on invoicer email."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error occurred.",
  "debug_id": "90957fca61718",
  "links": [
    {
      "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR",
      "rel": "information_link"
    }
  ]
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "details": [
    {
      "field": "string",
      "value": "string",
      "location": "body",
      "issue": "string",
      "description": "string"
    }
  ],
  "debug_id": "string",
  "links": []
}

Authorization

AuthorizationBearer <token>

Oauth 2.0 authentication

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

For managing (Create, Update, Delete) invoice.https://uri.paypal.com/services/invoicing/invoices/readwrite

Request Body

application/json

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

TypeScript Definitions

Use the request body type in TypeScript.

detail*

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

invoicer?

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

primary_recipients?array<>

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

Items0 <= items <= 100

additional_recipients?array<>

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.

Items0 <= items <= 100

items?array<>

An array of invoice line item information.

Items0 <= items <= 100

configuration?

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

amount?

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

payments?Payments

List of payments registered against the invoice..

refunds?Refunds

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

{ "id": "string", "parent_id": "string", "status": "DRAFT", "detail": { "reference": "string", "currency_code": "str", "note": "string", "terms_and_conditions": "string", "memo": "string", "attachments": [], "invoice_number": "string", "invoice_date": "stringstri", "payment_term": { "term_type": "DUE_ON_RECEIPT", "due_date": "stringstri" }, "metadata": { "create_time": "stringstringstringst", "created_by": "string", "last_update_time": "stringstringstringst", "last_updated_by": "string", "cancel_time": "stringstringstringst", "cancelled_by": "string", "first_sent_time": "stringstringstringst", "last_sent_time": "stringstringstringst", "last_sent_by": "string", "created_by_flow": "MULTIPLE_RECIPIENTS_GROUP", "recipient_view_url": "http://example.com", "invoicer_view_url": "http://example.com" } }, "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": { "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", "country_code": "st", "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": "str", "national_number": "string", "extension_number": "string", "phone_type": "FAX" } ], "website": "http://example.com", "tax_id": "string", "additional_notes": "string", "logo_url": "http://example.com" }, "primary_recipients": [], "additional_recipients": [], "items": [], "configuration": { "tax_calculated_after_discount": true, "tax_inclusive": false, "allow_tip": false, "partial_payment": { "allow_partial_payment": false, "minimum_amount_due": { "currency_code": "str", "value": "string" } }, "has_conditional_rule": false, "template_id": "PayPal system template" }, "amount": { "currency_code": "str", "value": "string", "breakdown": { "item_total": { "currency_code": "str", "value": "string" }, "discount": { "invoice_discount": { "percent": "string", "amount": { "currency_code": "str", "value": "string" } }, "item_discount": { "currency_code": "str", "value": "string" } }, "tax_total": { "currency_code": "str", "value": "string" }, "shipping": { "amount": { "currency_code": "str", "value": "string" }, "tax": { "name": "string", "percent": "string", "amount": { "currency_code": "str", "value": "string" }, "tax_note": "string" } }, "custom": { "label": "string", "amount": { "currency_code": "str", "value": "string" } } } }, "due_amount": { "currency_code": "str", "value": "string" }, "gratuity": { "currency_code": "str", "value": "string" }, "payments": { "paid_amount": { "currency_code": "str", "value": "string" }, "transactions": [] }, "refunds": { "refund_amount": { "currency_code": "str", "value": "string" }, "transactions": [] }, "links": [] }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "debug_id": "string", "links": [], "details": [ { "issue": "INVALID_STRING_MAX_LENGTH", "description": "Address line2 length should be less than 300 characters." } ] }

{ "name": "NOT_AUTHORIZED", "message": "Authorization failed due to insufficient permissions.", "details": [ { "field": "string", "value": "string", "location": "body", "issue": "string", "description": "string" } ], "debug_id": "string", "links": [] }

{ "name": "UNPROCESSABLE_ENTITY", "message": "The requested action could not be performed, semantically incorrect, or failed business validation.", "debug_id": "string", "links": [], "details": [ { "issue": "USER_NOT_FOUND", "description": "User is not associated with paypal based on invoicer email." } ] }

{ "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] }

{ "name": "INVALID_REQUEST", "message": "Request is not well-formed, syntactically incorrect, or violates schema.", "details": [ { "field": "string", "value": "string", "location": "body", "issue": "string", "description": "string" } ], "debug_id": "string", "links": [] }

Create draft invoice

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

defaultapplication/json

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Create draft invoice

Authorization

Request Body

Response Body

201application/json

400application/json

403application/json

422application/json

500application/json

defaultapplication/json

`application/json`

`application/json`