Upgrading from 3.12 to 3.13

info

To follow the zero-downtime strategy when upgrading to 3.13, we recommend migrating to 3.12.11 first and turn on the celery worker to process all data migrations asynchronously. Otherwise, you will need to downtime your solution to ensure correct data migration.

This migration guide describes the upgrade from versions 3.12 to 3.13. Version 3.13 contains the following breaking changes:

Mutation transactionCreate

The usage of the input fields for the transactionCreate mutation will change as follows:

• TransactionCreateInput
  • status - Saleor will calculate the status. The field can be skipped.
  • type - Use name and message instead.
  • reference - Use pspReference instead.
  • amountVoided - Use amountCanceled instead.
• TransactionEventInput:
  • status - Saleor will calculate the status. The field can be skipped.
  • reference - Use pspReference instead.
  • name - Use message instead.

All those fields will be removed in Saleor 3.14.

For each new transactionItem created by transactionCreate, any update action can be done only by the same app/user that performed transactionCreate action. These changes impact only new transactionItem. The existing ones will work the same way as before.

Mutation transactionUpdate

The usage of the input fields for the transactionUpdate mutation will change as follows:

• TransactionUpdateInput
  • status - Saleor will calculate the status. The field can be skipped.
  • type - Use name and message instead.
  • reference - Use pspReference instead.
  • amountVoided - Use amountCanceled instead.
• TransactionEventInput:
  • status - Saleor will calculate the status. The field can be skipped.
  • reference - Use pspReference instead.
  • name - Use message instead.

All those fields will be removed in Saleor 3.14.

For each new transactionItem created by transactionCreate, any update action can be done only by the same app/user that performed transactionCreate action. These changes has impact only on new transactionItem. The existing ones will work in the same way as before.

Mutation transactionEventReport

We highly recommend converting to transactionReportEvent. The new mutation simplifies the flow of reporting changes for the transaction. It is also more error-proof than transactionUpdate as Saleor does all calculations, and it requires providing a specific type of action that should be reported. transactionReportEvent mutation is idempotent, so the app doesn't need to build a de-duplication system on its side.

The below examples show calls of both mutations where the result will be the same.

For example, the query:

mutation {
  transactionUpdate(
    id: "VHJhbnNhY3Rpb25JdGVtOjE="
    transaction: {
      status: "Charged"
      availableActions: [REFUND]
      reference: "PSP-ref123.charge"
      amountAuthorized: { currency: "USD", amount: 0 }
      amountCharged: { currency: "USD", amount: 99 }
    }
    transactionEvent: {
      status: SUCCESS
      name: "Charged credit card"
      reference: "PSP-ref123.charge"
    }
  ) {
    transaction {
      id
    }
  }
}

Expand ▼

should be converted to:

mutation {
  transactionEventReport(
    id: "VHJhbnNhY3Rpb25JdGVtOjE="
    pspReference: "PSP-ref123.charge"
    type: CHARGE_SUCCESS
    amount: 99
    message: "Charged credit card"
    availableActions: [REFUND]
  ) {
    transaction {
      id
    }
  }
}

• transactionUpdate.id is the same as transactionEventReport.id
• transactionUpdate.transactionEvent.reference is transactionEventReport.pspReference
• transactionUpdate.transaction.reference is not needed
• transactionUpdate.transaction.amountAuthorized App doesn't need to make the reduction calculation in transactionEventReport.
• transactionUpdate.transaction.amountCharged is transactionEventReport.amount
• transactionUpdate.transaction.availableActions doesn't exist in transactionEventReport.availableActions. Saleor will calculate possible actions.
• transactionUpdate.transactionEvent.status is not needed. transactionEventReport.type covers all statuses
• transactionUpdate.transactionEvent.name is transactionEventReport.message

Webhook TRANSACTION_ACTION_REQUEST

TRANSACTION_ACTION_REQUEST is deprecated and will be removed in Saleor 3.14. Use synchronous webhooks: TRANSACTION_CHARGE_REQUESTED, TRANSACTION_REFUND_REQUESTED, TRANSACTION_CANCELATION_REQUESTED instead.

TransactionChargeRequested, TransactionRefundRequested, TransactionCancelationRequested (subscription types for above events) will have the same payload as webhook subscription of TRANSACTION_ACTION_REQUEST. The new webhooks are synchronous and require providing a pspReference in the returned payload.

The app implementation needs to be modified to provide at least a PSP reference in the response. The app on the Saleor side needs to be subscribed to the webhook with events TRANSACTION_CHARGE_REQUESTED, TRANSACTION_REFUND_REQUESTED, TRANSACTION_CANCELATION_REQUESTED. Webhook subscribtion for the event: transaction-action-request should be removed from the App.

Calling transactionReportEvent require HANDLE_PAYMENTS permission. (Previously it was MANAGE_ORDERS).

Order mutations

Mutations orderVoid, orderCapture, orderRefund, orderFulfillmentRefundProducts, orderFulfillmentReturnProducts will not trigger TRANSACTION_ACTION_REQUEST webhook no more. Use a dedicated mutation for triggering an action: transactionRequestAction.