Magento_Sales module

Magento_Sales module is responsible for order processing and appearance in the system.

Magento_Sales module manages next system entities and flows:

• order management
• invoice management
• shipment management (including track management)
• credit memos management

Magento_Sales module is required for Magento_Checkout module to perform checkout operations.

Public API

InvoiceOrder

The InvoiceOrder service introduces a capability to execute Magento native business flow of the Sales module using API.

With this service you can:

• create an invoice document (full or partial)
• capture money placed with order payment
• notify a customer about document creation
• change order status and state

Parameters

orderId

An identifier of a target order for operation.

Format: Integer

Presence: Required

items

An array of order items that will be included to invoice. By default, the invoice will contain all order items.

Format: Array of items with a format according to \Magento\Sales\Api\Data\InvoiceItemCreationInterface.

Default: []

Presence: Optional (required, when invoice must contain particular order items.

Example:

1
2
3
4
5
6
7
8
9
10
[
  {
      "order_item_id": 1,
      "qty": 2
  },
  {
  "order_item_id": 2,
  "qty": 0.5
  }
  ]

capture

Flag that sets whether the customer’s payment can be captured using an online payments system (for example, PayPal). IMPORTANT: If you created Invoice with the flag set to default value (false), you will not be able to capture money in Magento on the corresponding Invoice.

Format: Boolean

Default: false

Presence: Optional

notify

Flag that activates e-mail notification about new invoice for a customer. If true, the service will notify a customer. If false, the service won’t notify a customer.

Format: Boolean

Default: false

Presence: Optional

appendComment

Flag that determines whether a comment argument must be included in an e-mail notification. If true, the service adds the comment.

Format: Boolean

Default: false

Presence: Optional

comment

The comment to add to an invoice. Specify a comment if appendComment is set to true.

Format: A format according to \Magento\Sales\Api\Data\InvoiceCommentCreationInterface.

Default: null

Presence: Optional

Example:

1
2
3
4
{
  "comment": "The first Invoice",
  "is_visible_on_front": true
}

arguments

Additional arguments. Reserved for use by extension modules.

Format: A format according to \Magento\Sales\Api\Data\InvoiceCreationArgumentsInterface.

Default: null

Presence: Optional

Return values

The service returns an identifier of the created Invoice.

REST

POST Endpoint

http://<magento_host>/rest/<store_code>/V1/order/<orderId>/invoice

REST declaration

etc/webapi.xml

1
2
3
4
5
6
<route url="/V1/order/:orderId/invoice" method="POST">
    <service class="Magento\Sales\Api\InvoiceOrderInterface" method="execute"/>
    <resources>
        <resource ref="Magento_Sales::invoice" />
    </resources>
</route>

SOAP

SOAP Endpoint

http://<magento_host>/soap/<store_code>?wsdl&services=salesInvoiceOrderV1

PHP interface

\Magento\Sales\Api\InvoiceOrderInterface

PHP implementation

\Magento\Sales\Model\InvoiceOrder

Exceptions

In case of failure, it returns an error object. Example in REST:

1
2
3
{
  "message": "Creditmemo Document Validation Error(s):\nWe can't create creditmemo for the order.\nThe most money available to refund is 0."
}

Extension points

The service implementation contains extension points marked with @api annotation. Extension developers can use APIs to extend service logic.

RefundInvoice

The RefundInvoice service introduces a capability to execute Magento native business flow of the Sales module using API.

Please note, that current service is available only for invoices created using online payment methods. If you try to apply it to an Invoice created using offline payment method, system will throw a validation error.

With this service you can:

• create a Credit Memo (complete or partial) for particular Invoice
• add details about refunded items to an Order
• change status and state of an Order according to performed actions
• notify a customer about performed refund operation

Service parameters

invoiceId

An identifier of a target Invoice for operation.

Format: Integer

Presence: Required

items

An array of invoice items included to a Credit Memo. By default, the service will create a Credit Memo for all invoice items.

Format: Array of items with a format according to \Magento\Sales\Api\Data\CreditmemoItemCreationInterface.

Default: []

Presence: Optional (required, when a Credit Memo must contain particular order items).

Example:

1
2
3
4
5
6
7
8
9
10
[
    {
          "order_item_id": 1,
          "qty": 2
    },
    {
    "order_item_id": 2,
    "qty": 0.5
    }
]

isOnline

Flag that determines whether funds should be returned to a customer via online payment system (PayPal for example) or not.

Format: Boolean

Default: false

Presence: Optional

notify

Flag that activates e-mail notification about Credit Memo creation. If true, the service notifies a customer; if false, it doesn’t.

Format: Boolean

Default: false

Presence: Optional

appendComment

Flag that activates addition of a comment argument to the e-mail notification. If true and comment contains data, the service will add the comment to an e-mail notification.

Format: Boolean

Default: false

Presence: Optional

comment

A comment to Credit Memo.

Format: A format according to the \Magento\Sales\Api\Data\CreditmemoCommentCreationInterface.

Default: null

Presence: Optional

Example:

1
2
3
4
{
  "comment": "The first Credit Memo",
  "is_visible_on_front": true
}

arguments

Additional arguments for the service. Can be used by extension modules.

Format: A format according to \Magento\Sales\Api\Data\CreditmemoCreationArgumentsInterface.

Default: null

Presence: Optional

Example:

1
2
3
4
5
{
"shipping_amount": 10.00,
"adjustment_positive": 5.00,
"adjustment_negative": 5.00
}

A parameter shipping_amount behaves like at the Credit Memo creation page in the Admin area. If shipping amount is not specified, then shipping amount from a target Invoice is refunded automatically. To specify a shipping amount, consider shipping tax displays settings.

Return values

The service returns an identifier of a created Credit Memo.

REST

POST Endpoint

http://<magento_host>/rest/<store_code>/V1/invoice/<invoiceId>/refund

REST Declaration

etc/webapi.xml

1
2
3
4
5
6
<route url="/V1/invoice/:invoiceId/refund" method="POST">
    <service class="Magento\Sales\Api\RefundInvoiceInterface" method="execute"/>
    <resources>
        <resource ref="Magento_Sales::sales_invoice" />
    </resources>
</route>

SOAP

SOAP Endpoint

http://<magento_host>/soap/<store_code>?wsdl&services=salesRefundInvoiceV1

PHP interface

\Magento\Sales\Api\RefundInvoiceInterface

PHP implementation

\Magento\Sales\Model\RefundInvoice

Exceptions

In case of failure, it returns an error object. Example in REST:

1
2
3
{
  "message": "Creditmemo Document Validation Error(s):\nWe can't create creditmemo for the order.\nThe most money available to refund is 0."
}

Extension points

The service contains extension points marked with @api annotation. Extension developers can use APIs to extend service logic.

RefundOrder

With the RefundOrder service you can:

• create a Credit Memo (complete or partial) for a particular Order
• add details about refunded items to an Order
• change status and state of an Order according to performed actions
• notify a customer about performed refund operation

Service parameters

orderId

An identifier of a target Order for operation.

Format: Integer

Presence: Required

items

An array of Order items included to a Credit Memo. By default, the service will create a Credit Memo for all Order items.

Format: Array of items with a format according to \Magento\Sales\Api\Data\CreditmemoItemCreationInterface.

Default: []

Presence: Optional (required, when a Credit Memo must contain particular order items).

Example:

1
2
3
4
5
6
7
8
9
10
[
  {
        "order_item_id": 1,
        "qty": 2
  },
  {
        "order_item_id": 2,
        "qty": 0.5
  }
]

notify

Flag that activates e-mail notification about Credit Memo creation. If true, the service notifies a customer; if false, it doesn’t.

Format: Boolean

Default: false

Presence: Optional

appendComment

Flag that activates addition of a comment argument to the e-mail notification. If true and comment contains data, the service will add the comment to an e-mail notification.

Format: Boolean

Default: false

Presence: Optional

appendComment

Flag that activates addition of a comment argument to the e-mail notification. If true and comment contains data, the service will add the comment to an e-mail notification.

Format: Boolean

Default: false

Presence: Optional

comment

A comment to Credit Memo.

Format: A format according to the \Magento\Sales\Api\Data\CreditmemoCommentCreationInterface.

Default: null

Presence: Optional

Example:

1
2
3
4
{
  "comment": "The first Credit Memo",
  "is_visible_on_front": true
}

arguments

Additional arguments for the service. Can be used by extension modules.

Format: A format according to \Magento\Sales\Api\Data\CreditmemoCreationArgumentsInterface.

Default: null

Presence: Optional

Example:

1
2
3
4
5
{
"shipping_amount": 10.00,
"adjustment_positive": 5.00,
"adjustment_negative": 5.00
}

A parameter shipping_amount behaves like at the Credit Memo creation page in the Admin area. If shipping amount is not specified, then shipping amount from a target Invoice is refunded automatically. To specify a shipping amount, consider shipping tax displays settings.

Return values

The service returns an identifier of a created Credit Memo.

REST

POST Endpoint

http://<magento_host>/rest/<store_code>/V1/order/<orderId>/refund

REST Declaration

etc/webapi.xml

1
2
3
4
5
6
<route url="/V1/order/:orderId/refund" method="POST">
    <service class="Magento\Sales\Api\RefundOrderInterface" method="execute"/>
    <resources>
        <resource ref="Magento_Sales::creditmemo" />
    </resources>
</route>

SOAP

SOAP Endpoint

http://<magento_host>/soap/<store_code>?wsdl&services=salesRefundOrderV1

PHP interface

[\Magento\Sales\Api\RefundOrderInterface][]

PHP implementation

\Magento\Sales\Model\RefundOrder

Exceptions

In case of failure, it returns an error object. Example in REST:

1
2
3
{
  "message": "Creditmemo Document Validation Error(s):\nWe can't create creditmemo for the order.\nThe most money available to refund is 0."
}

Extension points

The service contains extension points marked with @api annotation. Extension developers can use APIs to extend service logic.

ShipOrder

With the ShipOrder service you can:

• create a shipment document (full or partial)
• add details about shipped items into an order
• change status and state of an order according to performed actions
• notify the customer of a new shipment document

Service parameters

orderId

An identifier of a target order for operation.

Format: Integer

Presence: Required

items

An array of order items included to a shipment. By default, the service will create a shipment for all order items.

Format: Array of items with a format according to \Magento\Sales\Api\Data\ShipmentItemCreationInterface.

Default: []

Presence: Optional (required, when a shipment document must contain particular order items).

Example:

1
2
3
4
5
6
7
8
9
10
[
  {
      "order_item_id": 1,
      "qty": 2
  },
  {
      "order_item_id": 2,
      "qty": 0.5
  }
]

notify

Flag that activates e-mail notification about shipment details. If true, the service notifies a customer; if false, it doesn’t.

Format: Boolean

Default: false

Presence: Optional

appendComment

Flag that activates addition of a comment argument to the e-mail notification. If true and comment contains data, the service will add the comment to an e-mail notification.

Format: Boolean

Default: false

Presence: Optional

comment

A comment about a shipment.

Format: A format according to the \Magento\Sales\Api\Data\CreditmemoCommentCreationInterface interface.

Default: null

Presence: Optional

Example:

1
2
3
4
{
    "comment": "The first Invoice",
    "is_visible_on_front": true
}

tracks

A list of track numbers attached to a shipment.

Format: Array of objects with a format according to \Magento\Sales\Api\Data\ShipmentTrackCreationInterface>.

Default: []

Presence: Optional

Example:

1
2
3
4
5
6
7
[
    {
        "track_number": "132456789",
        "title": "United States Postal Service",
        "carrier_code": "usps"
    }
]

packages

A list of packages attached to a shipment.

Format: Array of objects with a format according to \Magento\Sales\Api\Data\ShipmentPackageCreationInterface.

Default: []

Presence: Optional

Example:

1
2
3
4
5
6
7
8
9
10
11
12
13
[
    {
        "extension_attributes":
        {
            "ups":
                {
                    "weight": 20,
                    "height": 15,
                    "width": 20
                }
        }
      }
]

arguments

Additional arguments for the service. Can be used by extension modules.

Format: A format according to the \Magento\Sales\Api\Data\CreditmemoCreationArgumentsInterface interface.

Default: null

Presence: Optional

Return values

The service returns the identifier of a created shipment.

REST

POST Endpoint

http://<magento_host>/rest/<store_code>/V1/order/<orderId>/ship

REST Declaration

etc/webapi.xml

1
2
3
4
5
6
<route url="/V1/order/:orderId/ship" method="POST">
    <service class="Magento\Sales\Api\ShipOrderInterface" method="execute"/>
    <resources>
        <resource ref="Magento_Sales::ship" />
    </resources>
</route>

SOAP

SOAP Endpoint

http://<magento_host>/soap/<store_code>?wsdl&services=salesShipOrderV1

PHP interface

\Magento\Sales\Api\ShipOrderInterface

PHP implementation

\Magento\Sales\Model\ShipOrder

Exceptions

In case of failure, it returns an error object. Example in REST:

1
2
3
{
  "message": "Creditmemo Document Validation Error(s):\nWe can't create creditmemo for the order.\nThe most money available to refund is 0."
}

Extension points

The service contains extension points marked with @api annotation. Extension developers can use APIs to extend service logic.